Legal Information

Telephony Application Programming Interface (TAPI) Programmer's Reference

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, people, and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1995-2001 Microsoft Corporation. All rights reserved.

Active Directory, DirectShow, Microsoft, MSDN, MS-DOS, Visual Basic, Windows, Windows NT, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Microsoft Telephony Overview

Telephony integrates computers with communications devices and networks. Under classic telephony, the device was a telephone and the network was the Public Switched Telephone Network (PSTN). Modern telephony continually expands the range of devices and networks, and currently covers devices such as cameras and networks such as the Internet.

Possible telephony applications include:

  • Multicast multimedia IP conferencing
  • Voice calls over the Internet (VoIP)
  • Automatic Call Distribution (ACD) Center client and server applications
  • Basic voice calls on the PSTN
  • PBX-like controls such as call park and selective forwarding on a corporate phone network without the need to invest in specialized hardware
  • Interactive voice response (IVR) systems, such as the Web Telephony Engine (WTE)
  • Real Time Collaboration (RTC)

The Microsoft® Telephony application programming interfaces (TAPI, TSPI, and MSPI) support the development of communications applications for running operating systems that support the Microsoft Win32® API, such as Microsoft Windows® 95 or Microsoft Windows 2000.

The following diagram illustrates Microsoft Telephony architecture, and is hyperlinked as a basic roadmap to the material in this SDK. Please note that TAPI is not limited to PSTN, ISDN, or TCP/IP transport.


What's New

TAPI 3.1 adds detailed phone device controls and a number of specialized terminal interfaces. The following table lists the new interfaces.

Interface | Description
IEnumPhone | Provides enumeration methods for the ITPhone interface.
IEnumPluggableSuperclassInfo | Provides enumeration methods for the ITPluggableTerminalSuperclassInfo interface.
IEnumPluggableTerminalClassInfo | Provides enumeration methods for the ITPluggableTerminalClassInfo interface.
ITASRTerminalEvent | Retrieves the description of Automatic Speech Recognition terminal events.
ITAddress2 | Provides additional methods on the Address object that support phone devices; derives from the ITAddress interface.
ITAutomatedPhoneControl | Performs several high-level phone-related functions including enabling and configuring automated control of a phone's tones and rings, and automated call handling based on a phone's hookswitch state.
ITBasicCallControl2 | Extends the ITBasicCallControl interface by providing methods to select a terminal onto a call.
ITCallInfo2 | Extends the ITCallInfo interface by providing methods to set event filtering on a per-call basis.
ITCollection2 | Extends the ITCollection interface by providing additional methods for modifying the collection.
ITCustomTone | Provides methods that allow detailed control over the custom tones possible with some phone sets.
ITDetectTone | Provides methods that allow an application to specify to the TAPI Server the tones and tone characteristics that cause the server to generate a tone event.
ITDigitsGatheredEvent | Provides methods to retrieve data related to an application's digit-gathering request.
ITFileTerminalEvent | Retrieves the description of file terminal events.
ITFileTrack | Retrieves and sets information concerning file terminal tracks.
ITLegacyAddressMediaControl2 | Extends the ITLegacyAddressMediaControl interface by providing additional methods that allow the configuration of parameters related to line devices.
ITLegacyCallMediaControl2 | Extends the ITLegacyCallMediaControl interface by providing additional methods for tone detection and generation.
ITMediaControl | Starts, stops, and pauses current actions, such as a playback.
ITMediaPlayback | Provides playback-specific methods that allow an application to set and get the list of files to play.
ITMediaRecord | Provides recording-specific methods that allow an application to set and get the names of files to record.
ITMultiTrackTerminal | Enumerates, creates, or removes tracks on multitrack terminals.
ITPhone | Allows access to the phone device at a level comparable to that available with the TAPI 2.x C API.
ITPhoneEvent | Retrieves the description of phone events.
ITPluggableTerminalClassInfo | Retrieves information concerning a pluggable terminal.
ITPluggableTerminalClassRegistration | Creates, modifies, or deletes the registry entry for a pluggable terminal.
ITPluggableTerminalEventSink | Notifies client applications about changes in a pluggable terminal.
ITPluggableTerminalEventSinkRegistration | Registers and unregisters a client application for notification about pluggable terminal events.
ITPluggableTerminalInitialization | Performs primary terminal object creation for pluggable terminals, allowing the Terminal Manager to initialize the terminal.
ITPluggableTerminalSuperclassInfo | Retrieves the name and CLSID of a pluggable terminal class.
ITPluggableTerminalSuperclassRegistration | Retrieves and sets information about a terminal superclass (name and CLSID).
ITScriptableAudioFormat | Retrieves the audio format from, or sets the audio format for, a track.
ITStaticAudioTerminal | Provides methods on static audio terminal objects that are needed to support phone devices. TAPI 3.1 MSPs must expose this interface on all static audio terminals.
ITTAPI2 | Provides additional methods on the TAPI object to support phone devices; derives from the ITTAPI interface.
ITTAPIObjectEvent2 | Extends the ITTAPIObjectEvent interface; provides a method that returns a pointer to an ITPhone interface on the phone object that caused the TAPI object event.
ITTTSTerminalEvent | Retrieves the description of text-to-speech (TTS) terminal events.
ITTerminalManager2 | Retrieves information about pluggable terminal classes registered in the current system; derives from the ITTerminalManager interface.
ITTerminalSupport2 | Retrieves information about pluggable terminal classes and superclasses; derives from the ITTerminalSupport interface.
ITToneDetectionEvent | Retrieves information about a tone detection event.
ITToneTerminalEvent | Retrieves the description of tone terminal events.


TAPI Quick Start

The Telephony Application Programming Interface is an extensive and capable API. The following material is a series of links and suggestions that can help you start writing TAPI applications or adding functionality to existing code.

Code Samples

Code Snippets

Reference Page Summaries

Hyperlinked Graphics

TAPI Newsgroups

Code Samples

The samples section of the Platform SDK contains fully compilable TAPI programs in C, C++, and Visual Basic. These samples can help you begin to understand the uses of various functions. The exact location of the material depends on whether you have a full installation. If you have difficulty locating them, try a search on Incoming.cpp.

Code Snippets

The following SDK topics illustrate basic TAPI operations using code snippets.

  • Initialize TAPI
  • Select an Address
  • Register Events
  • Select a Terminal
  • Make a Call
  • Receive a Call
  • Create a Simple Conference
  • Transfer a Call

Reference Page Summaries

The following topics contain reference page summaries.

Area | Link
TAPI 2.2 | TAPI Quick Function Reference
TAPI 3.1 | Call and Media Control Quick Reference Rendezvous IP Telephony Conferencing Reference
TSPI | TSPI Quick Function Reference
MSPI | Media Service Provider Interface (MSPI) Reference

Hyperlinked Graphics

The following topics contain hyperlinked graphics that may be useful in orienting yourself in this SDK.

Microsoft Telephony Overview

About Call And Media Controls

Call Scenario Using A TSP/MSP Pair

TAPI Newsgroups

Usenet newsgroups can be good forums for the exchange of information and for assistance in debugging code. If you are not familiar with Usenet, this web page provides some basic description: http://extra.newsguy.com/intro.htm or type "Usenet Newsgroups" into your favorite search engine.

Microsoft hosts a number of newsgroups, including two specializing in TAPI.

News Server
msnews-gw
Groups
microsoft.public.win32.programmer.tapi

microsoft.public.win32.programmer.tapi.beta


The Microsoft Telephony Programming Model

The following material describes the components of Microsoft Telephony and how to use them to create powerful and flexible communication systems.

The Microsoft Telephony programming model abstracts communications control from device control, freeing end-user applications and device manufacturers from the need to march in lockstep. Using this model, an end-user or server application does not require detailed information on device control and the device does not need to be tailored to the application. Applications and devices can undergo innovation and change without rendering each other useless to customers.

The following diagram illustrates how this abstraction is accomplished:

These components can be viewed as repositories of specialized knowledge. The Telephony Application Programming Interface (TAPI) application knows user needs, the TAPI DLL and TAPISRV understand general telephony, and the service providers (TSP and MSP) know detailed device control. Application writers and device manufacturers require only general knowledge of each other's requirements.

  • An application loads the TAPI DLL into its process space and uses TAPI to communicate needs.
  • TAPI establishes an RPC link communications with the TAPI Server.
  • In addition, TAPI Version 3 creates an MSP object and communicates with it using a defined set of commands, the Media Service Provider Interface (MSPI).
  • When an application calls a TAPI operation, the TAPI dynamic-link library validates and marshals the parameters, then forwards the information to Tapisrv.exe.
  • TAPISRV tracks communications resources available to the local machine and interfaces with the Telephony Service Providers (TSPs) using the Telephony Service Provider Interface (TSPI).
  • Communications between a TSP and an MSP take place using a virtual connection that passes through the TAPI DLL and TAPISRV.
  • The TSP/MSP pair supplies information on device state and capabilities and implements the specific commands required for a desired response.

The result of using this programming model is that applications can ignore or adjust to device changes and new devices can be instantly useful instead of waiting on code base changes. Potential market share is expanded for both application writers and device manufacturers.

The following overview sections describe the Microsoft Telephony components in more detail.


TAPI Applications

The following material provides guidelines on using TAPI to write end-user or server communications applications. This information is also highly relevant to service provider programmers.

The first decision a programmer needs to make in using TAPI is the level of service required. For example, if an application requires a menu selection that can dial a phone number, a full TAPI application is probably not required. Assisted Telephony can enable this option quickly and simply. Please see TAPI Levels of Service for more information on the distinction between full TAPI applications and Assisted Telephony.

The second important decision is whether to use TAPI 2, the C-based API, or TAPI 3, which is based on COM. Please see TAPI 3.1 (TAPI/COM) or TAPI 2.2 (TAPI/C)? for a discussion of important considerations in deciding which one to use.

The following diagram illustrates the basic building blocks of a full TAPI application. TAPI 2 and TAPI 3 are both addressed in these sections. Material that is highly specific to one is addressed in the overview sections for TAPI 2 or TAPI 3.


TAPI Initialization

Proper functioning of TAPI components requires setting up the communications environment on a computer.

Installation is performed when software or hardware is first added to the computer. Detailed procedures depend on the operating system and the software itself.

Primary initialization creates the objects and communication paths.

Version negotiation ensures that TAPI components will be able to exchange data.

Resource inventory retrieves information concerning devices available for use by a TAPI application.

Event notification specifies how TAPI and the service providers pass asynchronous operation results and state change information to the application.

Summary of Related Reference Pages

TAPI 2 functions | Description
lineInitializeEx | Sets up the telephony environment, returns application handle and device count.
lineGetDevCaps | Gets device capabilities, such as TAPI version or media types supported.
lineGetAddressCaps | Gets address capabilities, such as whether call park is supported.
lineOpen | Notifies TAPI that the application will be using the line, and in what way.
lineGetMessage | Returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism

TAPI 3 interfaces or methods | Description
ITTAPI::Initialize | Sets up telephony environment.
ITTAPI::EnumerateAddresses | Enumerates addresses currently available.
ITTAPI::get_Addresses | Creates a collection of addresses currently available. Provided for Automation client applications, such as those written in Visual Basic.
ITTAPIEventNotification::Event | Determines response to an asynchronous event notification. Implemented by the application, invoked by TAPI.
ITTAPI::put_EventFilter | Sets the event filter mask, which notifies TAPI which events the application requires.
ITTAPI::RegisterCallNotifications | Instructs TAPI to pass the application incoming sessions for a specified address and set of media types.
ITMediaSupport | Allows an application to discover the media support capabilities for an address.


Installation

The primary sources for installation procedures are the Resource Kit for the target operating system, application documentation, and service provider instructions. For Microsoft® service providers, the appropriate resource kit contains instructions.

The installation process must include listing "Telephony Service" as dependency.

If an application or service provider uses the registry for storage of persistent private data, the information must not be placed in TAPI's section of the registry. The format of this section is not guaranteed to be maintained in future versions.


Primary Initialization

A TAPI application must call an initialization operation, which prompts a series of actions from TAPI and the service providers that set up the communication environment for the application.

  • Initialization is synchronous and does not return until the operation is complete or has failed.
  • If TAPISRV is not already running, TAPI starts it.
  • TAPI sets up a connection to the TAPISRV process.
  • TAPISVR loads the service providers specified in the registry and prompts them to initialize the devices they support.

TAPI 2 applications perform initialization by calling lineInitializeEx.

TAPI 3 applications call ITTAPI::Initialize.


Version Negotiation

Over time, different versions may exist for TAPI applications, TAPI, and the service providers. Optimal interoperability of a TAPI application requires knowledge of not just the application's TAPI version, but also of the TAPI DLL, TAPISVR, and service provider versions.

Failure to do proper version negotiation can result in serious problems. For example, some heavily used structures have data members added from one version to the next. If the structure size does not match what the application or TAPI expects, the consequences range from memory leaks to intermittent AVs.

For additional information on TAPI versioning, see TAPI 2 Versioning.

TAPI 2 applications negotiate with TAPI and TAPISVR during lineInitializeEx. Applications perform device negotiation with service providers by calling lineNegotiateAPIVersion for each line that the application might use.

TAPI 3 does not yet have different versions, so version negotiation is not needed.


Resource Inventory

The application must inventory the communications resources available to it, then notify TAPI about which resources it will use and how it will use them. See Device Control for additional information on the types of resources and capabilities an application might access.

TAPI 2 applications get the number of available lines when lineInitializeEx returns. They can then perform lineGetDevCaps on each line, lineGetAddressCaps for each address, and lineOpen for each line that will be used.

TAPI 3 applications use ITTAPI::EnumerateAddresses or ITTAPI::get_Addresses to discover the addresses available. ITMediaSupport and ITAddressCapabilities supply information on communication types possible for each address. If implemented by the service provider, ITTerminalSupport gives an application access to additional information and controls.


Event Notification

Event notification is the primary means by which an application gets information from TAPI and the service providers. This information may be the status of an asynchronous operation instigated by the application or may concern a process that started outside of the application, such as notifications of new incoming calls.

TAPI 2 applications handle notification in one of three ways: Hidden Window, Event Handle, or Completion Port. For additional information on these notification mechanisms, please see the Remarks section for lineInitializeEx. An application specifies the mechanism by setting the dwOptions member of the LINEINITIALIZEEXPARAMS structure prior to calling lineInitializeEx.

The lineSetStatusMessages function enables an application to specify which notification messages to receive for events related to status changes for the specified line or any of its addresses.

TAPI 3 applications handle general notification using COM standard connectable objects. ITTAPIEventNotification is the outgoing interface that must be registered with TAPI's container object, and ITTAPIEventNotification::Event is the method TAPI calls to determine the application's response. The ITTAPI::put_EventFilter method tells TAPI which events are of interest to the application. If an event filter is not entered, the application will not receive notification of any events. The ITTAPI::RegisterCallNotifications method tells TAPI the media types and addresses for which the application will handle incoming sessions. For additional information on TAPI 3 event handling, please see the Events overview or the Register Events code snippet.

Telephony service providers implement TSPI_lineSetDefaultMediaDetection and TSPI_lineSetStatusMessages. TAPI calls these functions to indicate the set of all line, address, and media type events requested by applications.


Device Control

Device control at the end-user or server application level requires a relatively small set of basic information. The service provider abstraction layer performs detailed device control. The service providers report required device information to an application through TAPI.

Key device categories include:

  • Network: The transport layer for communications. From an application's point of view, information about the network is typically embedded in the address type, such as LINEADDRESSTYPE_PHONENUMBER.
  • Line: A connection to a network. This concept is heavily used within TAPI 2.2 (TAPI/C).
  • Channel: A subdivision of a line. Knowledge of channels is normally not required of an application because the service provider configures how they will appear as addresses.
  • Address: A network location on a network. Each line or channel has one or more associated addresses. The address is a key concept in both TAPI 3.0 (TAPI/COM) and TAPI 2.2 (TAPI/C).
  • Terminal: A source or renderer for a particular address and media type.

The service providers report device characteristics to TAPI in response to application queries. Service providers also initiate reports on changes in device state. These changes are then reported to an application based on the notifications requested during initialization.

Basic device characteristics are:

  • Device Class
  • Device Identifier
  • Address Type
  • Address Identifier
  • Device Events
  • Media Type
  • Terminal Type

In addition, the service providers supply information concerning the capacity of a given address to perform various session operations.

Supplemental characteristics may be associated with certain devices, if the service providers support them. A TAPI 2 application discovers capabilities by using the lineGetDevCaps and lineGetAddressCaps functions. TAPI 3 applications use the ITAddressCapabilities interface for this purpose.

TAPI 2 provides a special set of supplemental operations that the service provider may implement for use with phone devices. See Phone Devices Overview.

Extended capabilities are provider-specific and not directly covered by the Microsoft Telephony API. See TAPI 2 Extended Line Functions, Extended Telephony Phone Functions, or TAPI 3 Provider-Specific Interfaces.

Below is a summary of TAPI operations that query service providers on device characteristics and provide data on current state.

TAPI 2 functions | Description
lineGetDevCaps | Queries a specified line device to determine the telephony capabilities of associated addresses.
lineGetAddressCaps | Queries a specified line device to determine the telephony capabilities of specific address.
lineGetDevConfig | Returns an "opaque" data structure that stores the current configuration of a device.
lineSetDevConfig | Restores device configuration.
lineConfigDialog | Display a dialog box that allows the user to configure parameters related to the device.
lineGetID | Retrieves a stable device identifier that can be used in further TAPI function calls, or with a different API.
lineGetLineDevStatus | Queries device for current status, such as number of active calls.
lineSetLineDevStatus | Sets device status, such as setting a device as not in service.
lineGetIcon | Retrieves provider-specific icon for display to the user.
lineNegotiateExtVersion | Allows an application to negotiate an extension version to use with the specified line device.
lineDevSpecific | Gives access to device-specific features.
lineDevSpecificFeature | Sends device-specific features to the service provider.

TAPI 3 interfaces or methods | Description
ITAddressCapabilities | Gets information concerning an address's capabilities.
ITAMMediaFormat | Sets and gets DirectShow™ media format.
ITBasicAudioTerminal | Sets and gets standard audio terminal characteristics, such as volume.
ITMediaSupport | Gets information concerning an address's media support capabilities.
ITTerminal | Base interface for the Terminal object. Obtains information such as terminal class and media supported.
ITTerminalSupport | Gets information on available terminals and creates additional terminals.
Provider-Specific Interfaces | Service provider dependent.


Device Categories

The following sections describe key device categories frequently used in building TAPI applications. Typically, an application does not require precise knowledge of these devices because the service provider abstraction layer handles control.

  • Address
  • Channel
  • Line
  • Network
  • Terminal


Address

The concept of an address is core to most communications operations. An address represents a location on a network. The local assignment of an address to a line or channel typically takes place during the installation of the service provider but can be modified later. Details on the procedures involved can be found in the operating system's Resource Kit for Microsoft-supplied service providers and in the service provider documentation for non-Microsoft products.

A single address may be shared by more than one line device. Different switch vendors have different names for this concept, such as address bridging, multiple appearance directory number (MADN), or bridged appearance. An incoming call on a shared address is offered on all lines associated with the address. See LINEADDRESSSHARING_ Constants for a description of the configurations that TAPI recognizes.

The address itself is a string that identifies a location on a network. In the case of a telephone network, the address is a telephone number complete with national or international codes. If the network is IP-based, the address may be an IP address. See LINEADDRESSTYPE_ Constants for TAPI-defined address types. A service provider may define additional address types.

Address-Related Capabilities and Messages

Different addresses have different features, capabilities, and states. The service providers are the source of such information. TAPI's device-query capability and status and event-reporting mechanisms give an application the information to manage addresses.

Applications acquire this information by processing events from TAPI or by using query operations. This allows an application to take into account factors such as whether a given address supports a specific capability, such as park.

TAPI 2 applications call the lineGetAddressCaps function to determine the telephony capabilities of each address and then receives this information in a LINEADDRESSCAPS data structure. In a similar way, an application can call lineGetDevCaps for a line device to determine the number of addresses assigned to the line, as well as other information.

TAPI 3 applications use the Address Object Interfaces to acquire information on address capabilities and events.

Storing Phone Numbers in Electronic Address Books

Many users choose to dial people, fax machines, bulletin boards, and other entities by selecting their names from an address book. The actual number dialed depends on the geographic location of the user and the way the line device to be used is connected. For example, a desktop computer can have access to two lines, one connected to a PBX, the other to the telephone company's central office. When making a call to the same party, different numbers may have to be used. (To dial through the PBX, for example, the computer may need to dial a "9" prefix to get an outside line, or a different prefix may be needed for a call made through the central office.) Or, a user may make calls from a portable computer and want to use a single, static address book even when calling from different locations or telephony environments. TAPI's address translation capabilities let the user inform the computer of the current location and the desired line device for the call. TAPI then handles any dialing differences, requiring no changes to the user's address book. An application uses address translation to convert an address from the canonical address format to the dialable address format.

A related topic is the handling of international call-progress monitoring, which is the process of listening for audible tones such as dial tone, special information tones, busy signals, and ringback tones to determine the state of a call (its progress through the network). Because the cadences and frequencies of call-progress tones vary from country/region to country/region, the service provider must know what call progress to follow when making an international outgoing call. Therefore, applications specify the destination country code when placing outgoing calls.

Canonical Addresses

The canonical address format is intended to be a universally constant directory number. For this reason, numbers in address books are best stored using canonical format.

The following details concern what is considered canonical for a phone address.

A canonical phone address is a text string with the following structure:

+ CountryCode Space [(AreaCode) Space] SubscriberNumber | Subaddress ^ Name CRLF ...

The components of this structure are described in the following table.

Component | Meaning
+ | Equivalent to hex 2B. Indicates that the number that follows it uses the canonical format.
CountryCode | A variably sized string containing one or more of the digits "0" through "9" (hex 30 through 39, inclusive). The CountryCode is delimited by the following Space. It identifies the country/region in which the address is located.
Space | Exactly one space character (hex 20). It is used to delimit the end of the CountryCode part of an address.
AreaCode | A variably sized string containing zero or more of the digits "0" through "9" (hex 30 through 39, inclusive). AreaCode is the area code part of the address and is optional. If the area code is present, it must be preceded by exactly one left parenthesis character (28), and be followed by exactly one right parenthesis character (29) and one space character (20).
SubscriberNumber | A variably sized string containing one or more of the digits "0" through "9" (hex 30 through 39, inclusive). It may include other formatting characters as well, including any of the dialing control characters described in the Dialable Address Format:
 | Character | Hex encoding
 | ! # $ * , ? @ ABCD P T W abcd p t w | 20 23 24 2A 2C 3F 40 41-44 50 54 77 61-64 70 74 79
 | The subscriber number should not contain the left parenthesis or right parenthesis character (which are used only to delimit the area code), nor should it contain the "|", "^", or CRLF characters (which are used to begin following fields). Most commonly, nondigit characters in the subscriber number would include only spaces, periods ("."), and dashes ("-"). Any allowable nondigit characters that appear in the subscriber number are omitted from the DialableString returned by the lineTranslateAddress function, but are retained in the DisplayableString.
| | Hex (7C). If this optional character is present, the information following it up to the next + | ^ CRLF, or the end of the canonical address string, is treated as subaddress information, as for an ISDN subaddress.
Subaddress | A variably sized string containing a subaddress. The string is delimited by + | ^ CRLF or the end of the address string. During dialing, subaddress information is passed to the remote party. It can be such things as an ISDN subaddress or an e-mail address.
^ | Hex (5E). If this optional character is present, the information following it up to the next CRLF or the end of the canonical address string is treated as an ISDN name.
Name | A variably sized string treated as name information. Name is delimited by CRLF or the end of the canonical address string and can contain other delimiters. During dialing, name information is passed to the remote party.
CRLF | Hex (0D) followed by Hex (0A), and is optional. If present, it indicates that another canonical number is following this one. It is used to separate multiple canonical addresses as part of a single address string (inverse multiplexing). For example, the canonical representation of the main switchboard telephone number at Microsoft Corporation would be: +1 (425) 882-8080

Dialable Addresses

The dialable address format is the form in which an address is passed to a service provider that handles telephone numbers. The following details concern dialable addresses on a phone network.

The dialable number format allows multiple destination addresses to be supplied at once. This ability can be useful if the service provider offers some form of inverse multiplexing by setting up calls to each of the specified destinations and then managing the information stream as a single high-bandwidth media stream. The application perceives this group of calls as a single call because it receives only a single call handle representing the aggregate of the individual phone calls.

It is also possible to support inverse multiplexing at the application level. To do this, the application would set up a series of individual calls and synchronize their media streams.

Subaddressing is a capability provided on ISDN lines that allows more information than just a single telephone number to be used when dialing. This additional information can specify an individual telephone extension to ring or, in a computing environment, a particular application to be alerted. Other parameters can describe the required aspects of a requested connection, such as rate and timing.

If subaddressing is supported by a service provider, the application includes this in the address passed to any operation that requires one.

A dialable phone address contains part addressing information and is part navigational in nature. Any input string that does not begin with a "+" character is presumed not to be in canonical format and therefore to be in dialable address format, and is returned to the application unmodified. A dialable address is a text string with the following structure:

DialableNumber | Subaddress ^ Name CRLF ...

The components of this structure are given in the following table.

Component | Meaning
DialableNumber | Digits and modifiers 0-9 A-D * # , ! W w P p T t @ $ ? ; delimited by | ^ CRLF or the end of the dialable address string. The plus sign (+) is a valid character in dialable strings. It indicates that the phone number is a fully-qualified international number. Within the DialableNumber, note the following definitions: 0-9 A-D * # Characters corresponding to the DTMF and/or pulse digits.
! | Hex (21). Indicates that a hookflash (one-half second onhook, followed by one-half second offhook before continuing) is to be inserted in the dial string.
P p | Hex (50) or Hex (70). Indicates that pulse dialing is to be used for the digits following it.
T t | Hex (54) or Hex (74). Indicates that tone (DTMF) dialing is to be used for the digits following it.
, | Hex (27). Indicates that dialing is to be paused. The duration of a pause is device specific and can be retrieved from the line's device capabilities. Multiple commas can be used to provide longer pauses.
W w | Hex (57) or Hex (77). An uppercase or lowercase W indicates that dialing should proceed only after a dial tone has been detected.
@ | Hex (40). Indicates that dialing is to "wait for quiet answer" before dialing the remainder of the dialable address. This means to wait for at least one ringback tone followed by several seconds of silence.
$ | Hex (24). Indicates that dialing the billing information is to wait for a "billing signal" (such as a credit card prompt tone).
? | Hex (3F). Indicates that the user is to be prompted before continuing with dialing. The provider does not actually do the prompting, but the presence of the "?" forces the provider to reject the string as invalid, alerting the application to the need to break it into pieces and prompt the user in-between.
; | Hex (3B). If placed at the end of a partially specified dialable address string, it indicates that the dialable number information is incomplete and more address information will be provided later. The ";" component is only allowed in the DialableNumber portion of an address.
| | Hex (7C), and is optional. If present, the information following it up to the next + | ^ CRLF, or the end of the dialable address string is treated as subaddress information (as for an ISDN subaddress).
Subaddress | A variably sized string containing a subaddress. The string is delimited by the next + | ^ CRLF or the end of the address string. When dialing, subaddress information is passed to the remote party. It can be for an ISDN subaddress, an e-mail address, and so on.
^ | Hex (5E), and is optional. If present, the information following it up to the next CRLF or the end of the dialable address string is treated as an ISDN name.
Name | A variably sized string treated as name information. Name is delimited by CRLF or the end of the dialable address string. When dialing, name information is passed to the remote party.
CRLF | Hex (0D) followed by Hex (0A). If present, this optional character indicates that another dialable number is following this one. It is used to separate multiple dialable addresses as part of a single address string (for inverse multiplexing).

Address translation can be used to translate an address from canonical format to dialable format.


Channel

Each line has one or more channels. The service providers normally handle how channels are exposed as addresses to an application, and the end user or server does not require specific knowledge of channels.

Channels are identical and therefore interchangeable. In POTS (Plain Old Telephone Service), exactly one channel exists on a line, and the channel is used exclusively for voice. With ISDN, at least three (and as many as 30 or more) channels can exist on a line simultaneously.

Each channel can have its own address, which means a line could have as many addresses as it has channels. The precise relationship between channels and addresses exposed to an application is dependent on a service provider's implementation.

Some service providers support the assignment of more than one address to a single channel. On POTS lines, multiple addresses are made possible by various systems, such as direct inward dialing (DID) or distinctive ringing, which are extra-fee services that the telephone company provides.

Many large corporations use DID for incoming calls. Before a call is connected, its destination extension number is signaled to the PBX, which causes the extension to ring instead of the operator's phone. An example of distinctive ringing in a private home would be if the parents used one address, the children another, and a fax machine a third. Because only one line connects the house to the telephone network, all phones ring when a call appears, but the ring pattern is different depending on the number that the calling party dialed. With distinctive ringing, the people know who the incoming call is for, and the fax machine answers its calls by recognizing its own ringing style.

In ISDN, the various B channels might not have separate addresses. Because these B channels might be on the same address, it is the service provider (and not the application or a person who has dialed the number) that assigns calls to these channels.


Line

The line concept has evolved over time and been partly superseded by the Address and Terminal concepts. TAPI 3 does not directly use the concept of line, but TAPI 2 continues to incorporate this paradigm.

A line device is a physical device such as a fax board, a modem, or an ISDN card that is connected to a network. The device may not be physically connected to the computer on which the TAPI application is running, such as a modem pool on a server. Line devices support communications capabilities by allowing applications to send information to or receive information from a network. A line device contains a set of one or more homogeneous channels that can be used to establish calls.

Within TAPI 2 applications, a line device is the logical representation of a physical telephone device. Although "line" often connotes something with two endpoints, it is possible to abstract a line device to a single point because TAPI views it only as a point of entry to the line that leads to the switch.

Although the three lines in the preceding illustration are composed of different hardware and used for different functions, they are abstracted to the same device type and governed by the same rules. The telephone represents not a phone device but a line device used for voice calls. When using this line device for incoming or outgoing calls, the application would also need to open and control an instance of the phone-device class, which is described in detail in later sections.

The line device class is a device-independent representation of a physical line device, such as a modem. It can contain one or more identical communications channels (used for signaling and/or information) between the application and the switch or network. Because channels belonging to a single line have identical capabilities, they are interchangeable. In many cases (as with POTS), a service provider will model a line as having only one channel. Other technologies, like ISDN, offer more channels, and the service provider should treat them accordingly.

TAPI 2 applications discover line capabilities using the lineGetDevCaps function. Version negotiation using the lineNegotiateAPIVersion lineNegotiateExtVersion functions must have been previously called.

TAPI 3 applications rely primarily on the address concept.


Network

A network is viewed as the transport mechanism that conveys data from one point to another. TAPI service providers handle the specific protocols required to perform operations such as establishing a communications session on a given network. An end-user or server application normally requires only very general network information, such as address type.

Some common types of networks:

  • POTS (Plain Old Telephone Service): Voice and data are transmitted in analog format while in the local loop and are digitally transmitted elsewhere. Typically, one media type per call, one channel per line.
  • ISDN (Integrated Services Digital Network): Transmitted digitally. Speeds of up to 128 Kbps on Basic Rate Interface (BRI-ISDN) lines and much higher on Primary Rate Interface (PRI-ISDN) lines. At least three channels and as many as 32 channels, for simultaneous, independently operated transmission of voice and data. International standard.
  • T1/E1: Transmitted digitally. T1 is a transmission link with a capacity of 1.544 Mbps, typically used for connecting networks across remote distances. In Europe T1 is called E1.
  • Switched 56: Signaling at 56 Kbps over dial-up telephone lines, but requires special equipment. Limited to calls to other specially equipped facilities.
  • CENTREX: Centralized network services through regular telephone lines and using telephone company equipment. No special equipment required.
  • Digital PBXs (private branch exchanges) and key systems: Voice and data transmitted on private telephone systems using proprietary interfaces.
  • IP Networks: Voice and data transmitted on networks using the Internet Protocol (IP), such as the Internet itself or a corporate intranet.

Please note that this list is not exhaustive. Any network transport mechanism can be supported, given appropriate service providers.


Terminal

A terminal is a source or renderer for a particular address and media type. The terminal concept is primarily used in TAPI 3 and is only mildly important to TAPI 2 applications. Please see the TAPI 3 Terminal Object overview topic for additional information.


Device Data

The following material covers the device-related information that a service provider can expose and that a TAPI application can use in operations such as resource inventory and session control.

  • Address Identifiers
  • Address Type
  • Device Class
  • Device Events
  • Device Identifier
  • Media Type
  • Terminal Type


Address Identifiers

After address assignment, TAPI assigns address identifiers to the addresses. An address identifier is a number between 0 and the number of addresses on the line minus one. An address identifier is a permanent number assigned to a given device and remains constant even across operating system upgrades. The combination of device identifier and address identifier uniquely identifies a given address.

A TAPI 2 application obtains an address identifier (and the device identifier) during a call to lineMakeCall or lineGetCallInfo, in the LINECALLINFO structure, or in a call to lineGetAddressID.

In TAPI 3, the ITAddressCapabilities::get_AddressCapability called AddressCap set to the AC_ADDRESSID member of ADDRESS_CAPABILITY will return with the plCapability parameter set to the current address ID.


Address Type

The device address type describes the forms of addressing permissible on an address, such as a phone number or an IP address. A given device will understand one or more address types. For a list of address types supported by TAPI, see LINEADDRESSTYPE_ Constants. Address translation may be used to convert an address from one type to another.

For general information on addresses, see Address under Device Categories.

The address type for a session will be a subset of the device address types.

TAPI 2: lineGetDevCaps, dwAddressType member of LINEDEVCAPS.

TAPI 3: ITAddressCapabilities::get_AddressCapability, with AddressCap set to the AC_ADDRESSTYPES member of ADDRESS_CAPABILITY.


Device Class

Device classes simplify development by letting programmers treat devices that have similar properties in a similar manner. For example, a digital phone in an office typically has more capabilities than a standard handset in a home, but both respond in much the same way to a basic set of functions, and both belong to a phone device class. Device classes help make TAPI extensible by providing a framework from which to classify and support new equipment.

See TAPI Device Classes for classes that TAPI has predefined. A service provider may implement and define additional device classes for the equipment it supports. An application never needs to know which service provider controls which device, but may require information on the control of new device classes.

A service provider implements a device class by mapping requests into actual device commands. For example, when the service provider for a Hayes-compatible modem receives a command passed through TAPISVR to make a call, it sends classic AT commands to the modem.

The service provider interface can be mapped to a wide range of environments, including those not traditionally thought of as belonging to telephony. An example is multimedia conferencing over an IP-based network such as the Internet.

Application developers should keep in mind the existence of other applications that may share telephony services.

TAPI 2 and TAPI 3: TAPI Device Classes


Device Events

TAPI responds to device changes such as a phone that has started ringing or a modem that has been removed by firing device events. A TAPI application should respond to a device event by querying for the specific change that has occurred and then taking appropriate action. An application may screen for events it will receive using event notification.

A TAPI 2 application receives notification of device events using the LINE_LINEDEVSTATE message. The current status of an address is determined by calling lineGetAddressStatus, which returns its information in a LINEADDRESSSTATUS structure. The status of a specified open line device is obtained by calling lineGetLineDevStatus, which returns its information in a LINEDEVSTATUS structure.

A TAPI 3 application receives an ADDRESS_EVENT notification, which is processed using the ITAddressEvent interface. The ITAddressCapabilities can then be used to acquire more detail information.


Device Identifier

A device ID is an application-independent identifier for a specific communications device. It is typically needed only when a TAPI application needs to hand off part of the processing involving in a communications session to the functions of a different API. For example, TAPI 2.2 applications may be unable to directly access a media stream and might use the Wave API.

TAPI 2: lineGetID

TAPI 3: ITAddressCapabilities::get_AddressCapability (AddressCap set to the AC_PERMANENTDEVICEID member of ADDRESS_CAPABILITY)


Media Type

The media type (or mode) of a device describes the type of information that can be exchanged, such as interactive voice. A given device might be able to handle only one media type, or it might be able to deal with a range of types.

Service providers expose the media type or types supported by the devices they control. Applications query for media type and then use this information to select an appropriate address on which to initiate a session. Application response to a session offered may also be predicated on media type.

A given communications session, or call, can involve several media types. For further information, see Media type for a session.

TAPI 2: lineGetAddressCaps, dwAvailableMediaModes member of LINEADDRESSCAPS structure pointed to by lpAddressCaps, LINEMEDIAMODE_ Constants

TAPI 3: ITTerminal::get_MediaType, TAPIMEDIATYPE_ Constants


Terminal Type

The terminal type identifies whether a terminal is static or dynamic. For example, a modem is a static terminal while the video window on a computer screen gets created when it is needed and destroyed when its usefulness is over.

This concept is primarily used by TAPI 3 applications.

TAPI 3: ITTerminal::get_TerminalType, TERMINAL_TYPE


Session Control

A session or call represents a connection between two or more addresses. This connection is dynamic, and the associated programming objects must be created, manipulated, and released as needed. In the simplest case, this means making and disconnecting a phone call. For advanced applications, session control may involve managing multimedia conferences over an IP network down to the level of individual participants.

Session control involves two basic areas:

Session Operations are controls that initiate, maintain, and terminate a communications session.

Session Information describes data that can be obtained concerning a communications session.

Two specialized types of session control are not covered in this section. For information on Automatic Call Distribution Centers, see TAPI 2's Call Center Control or About TAPI 3.0 Call Center Controls. For information on IP conferencing, see About Rendezvous IP Telephony Conferencing.


Session Operations

Session operations are the core of most TAPI applications. The following material provides an overview of various types of session control and links to the appropriate reference pages on functions and methods.

The following table summarizes TAPI session operations.

Session operations | TAPI 2 | TAPI 3
Initiate a session | lineMakeCall lineTranslateAddress | ITAddress::CreateCall ITAddressTranslation ITAddressTranslationInfo
Respond to session initiated elsewhere | lineAnswer lineAccept | ITBasicCallControl::Answer
Session changes Complete Conference Dial Drop Forward Handoff Hold Park Pickup Redirect Secure a session Transfer | lineCompleteCall lineUnCompleteCall linePrepareAddToConference lineAddToConference lineSetupConference lineGetConfRelatedCalls lineDial lineDrop lineForward lineHandoff lineHold lineSwapHold lineUnhold linePark lineUnpark linePickup lineRedirect lineSecureCall lineBlindTransfer lineSetupTransfer lineCompleteTransfer | ITBasicCallControl::Connect ITBasicCallControl::Disconnect ITBasicCallControl::Conference ITBasicCallControl::RemoveFromConference ITBasicCallControl::Finish ITBasicCallControl::Dial ITAddress::Forward ITBasicCallControl::HandoffDirect ITBasicCallControl::HandoffInDirect ITBasicCallControl::Hold ITBasicCallControl::ParkDirect ITBasicCallControl::ParkInDirect ITBasicCallControl::Pickup ITBasicCallControl::Transfer ITBasicCallControl::BlindTransfer
Terminate a session | lineDrop lineDeallocateCall | ITBasicCallControl::Disconnect Release interfaces involved in a session, usually at least ITCall, ITCallInfo, and ITBasicCallControl.


Initiate a Session

The primary pieces of information an application supplies to initiate a communications session are the address type, the media type or types, and the destination address.

The destination address may require address translation to put the information entered by a user into the proper format for a given address type. For example, a phone number that was in an electronic address book in canonical format will require translation to dialable format.

Some sessions may require special setup parameters, if supported by the service provider. For example, an ISDN TSP can transmit user-user information, and some MSPs require information about media stream direction. Please see Session Information for a review of data that may be set or obtained concerning a session.

Once a session has been initiated, TAPI will inform the application of call progress using the event notification mechanism set up during initialization.

TAPI 2 applications initiate a session using the lineMakeCall function. The lineTranslateAddress function is used to perform address translation, if required.

Call setup parameters can be stored in the LINECALLPARAMS data structure, and a pointer to this structure is then used as a parameter of lineMakeCall. If no LINECALLPARAMS structure is supplied to lineMakeCall, a default POTS voice-grade call is requested with a set of default values.

If the session is set up successfully, a call handle with owner privileges is returned to the application and TAPI sends the application LINE_CALLSTATE messages with information concerning the call's progress. Applications typically use these messages to display status reports to the user.

TAPI 3 applications initiate a communications session by invoking the ITAddress::CreateCall method on an address capable of handling the address type and media type required. If the address exposes the ITTerminalSupport interface, terminals are selected onto the media streams of the call object. Please see the Make a Call code snippet for an example of this process.

Call setup parameters can be stored or changed using methods exposed by the ITCallInfo interface.

If the session is set up successfully, TAPI returns an ITBasicCallControl interface pointer that can be used for further session operations, or to obtain an ITCallInfo interface pointer that can be used to acquire additional session information. The ITCallStateEvent interface processes TAPI call state events.

Note TAPI should not be used for fax transmissions. Instead, use the functions available through MAPI, the Microsoft Messaging API.

Address Translation

An end-user or server application may store addresses in a format that is not compatible with the needs of a given service provider. For example, a phone number may be stored in an electronic address book in canonical format, but most service providers that handle phone numbers require the dialable format.

TAPI supplies address translation operations that assist an application in presenting the correct address type to a TSP. The service provider specifies to TAPI which address types it supports, and need not include any form of address translation.

TAPI 2: lineTranslateAddress

TAPI 3: ITAddressTranslation, ITAddressTranslationInfo

Toll Lists

In some locations in North America, all telephone calls placed to the local area code are local calls. In other locations, some calls placed to the local area code are long distance, and need a "1" prefix to be dialed. The first three digits of the address (the prefix) determine whether or not a call within the local area code is a toll call.

A toll list is a list of prefixes in the local area code whose addresses must be dialed as long-distance addresses, and are assessed long-distance charges.

Toll lists are not relevant to service providers, or to applications that do not access a telephone network.

TAPI 2: lineTranslateAddress (LINETRANSLATERESULT_INTOLLLIST and LINETRANSLATERESULT_NOTINTOLLLIST bits in the LINETRANSLATEOUTPUT structure), lineSetTollList

TAPI 3: ITAddressTranslation::TranslateAddress, ITAddressTranslationInfo::get_TranslationResults


Respond to Session Initiated Elsewhere

When a new communications session arrives, TAPI applications that registered an interest in the address and media type will be sent an event notification. Only one application will be offered ownership privileges over the session. This application cannot refuse the session.

The initial call state of an incoming session is offering. While the call is in the offering state, an application can obtain information such as bearer mode and call reason, if the service providers supplied this information and it is available. Some call information may not be available immediately, such as caller ID.

There are six basic responses to an offered session: answer, accept, handoff, drop, forward, and redirect. Depending on the service provider, the full set of these operations may not be available.


Accept

In some environments, a user is not automatically alerted to an offering call, such as by ringing or by a message on their computer screen. The accept operation starts the process of alerting (usually ringing), and the answer operation takes place afterward. The application may drop the session, redirect it, or accept it.

If the current service provider supports it, the application has the option to send user-user information at the time of the accept. There is no guarantee that the network will deliver this information to the calling party.

Not all service providers support use of this operation.

TAPI 2: lineAccept


Answer

The answer operation is an application's typical response to an offered communications session. If successful, this operation causes a session to transition into the connected state.

In some telephony environments (like ISDN), where user alerting is separate from call offering, the application has the option to accept a call prior to answering or to reject (drop) or redirect the offering call.

If an answer operation is performed for a new session when a session is already active, the effect this has on the existing active session depends on the service provider's capabilities. The first call can be unaffected, it can automatically be dropped, or it can automatically be placed on hold. TAPI will sent the appropriate event notifications concerning both calls.

In a bridged situation, if a call is connected but in the active state, it can be joined using the answer operation.

The application has the option to send user-user information at the time of the answer, if the service provider supports it.

TAPI 2: lineAnswer

TAPI 3: ITBasicCallControl::Answer


Complete a Session

Completion operations allow an application to specify how it wants to handle a session when factors such as a busy destination prevent normal connection.

The LINECALLCOMPLMODE_ Constants define the possible options an application might have, depending on service provider capabilities.

Multiple call completion requests might be outstanding for a given address at any one time. To identify individual requests, the implementation returns a completion identifier. Canceling a call completion request in progress also uses this call completion identifier.

TAPI 2: lineCompleteCall, lineUncompleteCall

TAPI 3: ITBasicCallControl::Connect, ITBasicCallControl::Disconnect


Conference

Advanced conferencing using IP-based networks is described in TAPI 3's Rendezvous IP Telephony Conferencing Overview. The following material relates to basic conferencing.

Conference sessions are sessions that include more than two parties simultaneously. They can be set up using either an external server-based bridge or a switch-based conference bridge.

In server-based conference sessions, all participating parties dial into the server, which mixes the media streams together and sends each participant the mix. There may be no notion of individual parties in the conference call, only that of a single call between the application and the bridge server. To TAPI, this type of conference call appears to be a normal one-to-one connection.

Switch-based conferencing proceeds in stages, some of which may be combined if the service provider supports it:

  1. Initiate an ordinary communications session.
  2. Create a conference session with its first member the party that initiated conferencing.
  3. Create a conference consultation session with the party at the other end of the current connection.
  4. Add the consultation session to the conference.

After a session becomes a member of a conference, the member's state reverts to conferenced. The state of the conference session typically becomes connected. The session identifiers to the conference and all the added parties remain valid. State events can be received about all calls. For example, if one of the members disconnects by hanging up, an appropriate state message can inform the application of this fact.

In TAPI version 2.0 and later, applications can use the "no hold conference" feature of PBXs by using the LINECALLPARAMFLAGS_NOHOLDCONFERENCE option; this feature allows another device, such as a supervisor or recording device, to be silently attached to the line.

When canceling the consultation session to the third party for a conference or when removing the third party in a previously established conference, the service provider may release the conference and revert the session back to a normal two-party connection. If this is the case, the conference session will transition to the idle state, and the only remaining participating session will transition from the conferenced to the connected state.

Not all service providers support conferencing.

TAPI 2: The lineSetupConference function takes the original two-party call as input, allocates a conference call, connects the original call to the conference, and allocates a consultation call whose handle is returned to the application.

If the application is going to add another member to the conference, a dial operation can be performed on the consultation call. The conference call handle and the consultation call connection are then used in the lineAddToConference function. Conference members may also be added using linePrepareAddToConference function, if supported by the service provider.

Conference members are removed using the lineRemoveFromConference function, if the service provider supports it.

Alternatively, a conference may be created using the lineSetupTransfer function, which returns a consultation call handle, and the lineCompleteTransfer function with the conference option (instead of the transfer option).

TAPI 3: The ITBasicCallControl::Conference method takes the existing session as input and creates a CallHub object if one does not already exist. The ITBasicCallControl::Finish method adds the consultation call to the CallHub. Additional consultation sessions may be created using ITAddress::CreateCall, and added using the Conference and Finish methods.

Note The capabilities of the addressed line device can limit the number of parties conferenced in a single call and whether or not a conference starts out with a normal two-party call.


Dial

Dial operations allow an application to send additional digits on a previously created session. An example use of partial dialing is to dial an extension. Partial dialing is sometimes referred to as incremental dialing or delayed dialing.

When the address provided is incomplete, dialing some of the digits may be delayed by placing a ";" (semicolon) at the end of the number. A dial operation is then used to send additional address information on the existing session, such as dialing the address of a party to which the call will be transferred.

Every service provider should reject a dial string that contains the ? character and let the application deal with it as appropriate. For example, the application could use partial dialing to dial the string, up to but not including the ? character, and then display a dialog to let the user signal when the rest of the dial string should be dialed.

An additional reason for an application to use partial dialing is if the service provider does not support one or more of the call progress detection control characters. These characters, which can occur in a dialable address, are W (wait for dial tone); @ (wait for quiet answer); and $ (wait for calling-card prompt tone). These and all other characters used in address strings are discussed in greater detail in Dialable Addresses.

The provider indicates which "wait for" dial string modifiers it supports. A TAPI 2 application finds this information in the dwDevCapFlags member of the LINEDEVCAPS structure returned by lineGetDevCaps. A TAPI 3 application calls ITAddressCapabilities::get_AddressCapability with AddressCap set to the AC_DEVCAPFLAGS member of ADDRESS_CAPABILITY.

The application can choose to prescan dialable strings for unsupported characters or it can pass the "raw" string as part of initiating a session. If the string contains an unsupported modifier or a ?, the provider will return an error indicating which offending modifier occurred first within the string:

  • LINEERR_DIALBILLING
  • LINEERR_DIALQUIET
  • LINEERR_DIALDIALTONE
  • LINEERR_DIALPROMPT

The application can then locate the offending modifier in the string, take the digits to the left of the modifier, append a semicolon, and initiate a session using the partial address. The remainder of the string can be sent using the dial operation.

Not all service providers support use of this operation.

TAPI 2: lineDial

TAPI 3: ITBasicCallControl::Dial


Drop

Dropping or disconnecting a session terminates communication. The application has the option of sending user-user information at the time of the disconnect, if the service provider supports it.

The usual reasons for dropping a session is a user has requested a disconnect or the other end of the session has dropped. A drop operation may also be called when TAPI offers a session to the application. If the service provider supports this, the effect is that the application rejects the call.

When invoking a drop operation, related sessions can sometimes be affected as well. For example, dropping a conference call can drop all individual participants. State change messages are sent to the application for all calls whose state is affected.

In various bridged or party-line configurations when multiple parties are on the call, a drop operation may not actually clear the call. For example, in a bridged situation, the call may not be dropped because the status of other stations on the call may govern. Instead, the call may simply be changed to the inactive state while remaining connected at other stations.

Following a drop operation, the session identifier and most resources associated with the session will remain usable for most query operations. When an application no longer requires these resources, it must terminate the session in order to avoid memory leaks.

TAPI 2: lineDrop

TAPI 3: ITBasicCallControl::Disconnect


Forward

Forwarding is the deflection of an incoming session to a different destination address. TAPI allows an application to specify a list of forwarding conditions for an address. Forwarding conditions can be as finely grained as a different destination and forwarding mode for each caller address.

The forwarding operation can also be used to implement a selective do-not-disturb feature, by forwarding some callers to voice mail and allowing others to attempt completion.

The forwarding operation can also cancel any forwarding currently in effect.

Some service providers require that an application create a consultation call prior to a forwarding operation. The forwarding operation is then passed a pointer to the consultation call.

Not all service providers support use of this operation.

TAPI 2: to set lineForward to get lineGetAddressStatus, change the LINE_ADDRESSSTATE notification message with LINEADDRESSSTATE_FORWARD.

TAPI 3: ITAddress::Forward , ITAddress::get_CurrentForwardInfo, change notification: ITAddressEvent::get_Event with AE_FORWARD.

Note It may be impossible for a service provider to know at all times what forwarding is in effect for an address. Forwarding can be canceled or changed in ways that do not result in notification to the service provider.


Handoffs

When an application has owner privilege for a communications session, the application may choose to hand off ownership to another application. The handoff operation is normally used to allow the call's media type to be changed. The highest-priority application for the new media type should take and handle the call. Media type changing usually occurs for one of the following reasons.

User command: Through a user interface or through window messages, the application learns that the local user wants to change media type. For example, the user has told the new target application (which is not yet an owner) to obtain an existing voice call for transmitting data. The target application must now take control of the call. In this case, the current owner notices the number of owners increase, and then relinquishes its control of the call. Alternatively, the user could instruct the current owner of the call to hand it off to an application that can handle the new media type.

Media type change: The service provider can detect a media type change. For example, the local application is playing a recorded voice message to the caller. During this message, the caller spontaneously decides to transmit a fax calling tone, and the local application can respond accordingly by changing the media type to fax and, if necessary, handing the call off to a fax application. Another way this can work is for a monitoring application to enable media type monitoring, and, when the media type in which it is interested is detected on a call, it can request ownership of the call. This mechanism makes it unnecessary for every application to monitor every call for every media type.

Remote party command: The remote party can interactively indicate a change in media types during an existing call, such as if the local application is monitoring DTMF input by the remote caller. Through this monitoring, the caller indicates, for example, that a fax is about to be sent. Other ways the caller can control local applications are with commands received on other data connections and through ISDN user-user information messages.

A call handoff will have one of these outcomes:

  • The call is given to another application (SUCCESS).
  • The handing-off application is itself the target (TARGETSELF).
  • The handoff fails (TARGETNOTFOUND).

If the application that is receiving the handed-off call already has a call handle to the call, this old call handle is used. Otherwise, a new call handle is created. In either case, the application ends up with owner privileges to the call. Whenever the handing-off application is not the same as the target application, the target is informed about the handoff in a session state message as if it were receiving a new call.

If the current owner application is told to change media types, it does so by handing off the call to an application used for the target media type. The two types of call handoffs are described in Directed Handoffs and Media type Handoffs.

Not all service providers support use of this operation.

TAPI 2: lineHandoff, with lpszFileName set to the application name for a direct handoff or dwMediaMode set to one media type for an indirect handoff.

TAPI 3: ITBasicCallControl::HandoffDirect, ITBasicCallControl::HandoffIndirect

Directed Handoffs

A directed handoff takes place when the target application is known by name to the original application. This situation would occur, for example, among a set of applications written by the same vendor. The user can usually configure control of directed handoffs. With such a handoff, the call is given to the specified application if it has opened the line on which the call exists. The media type specified at the time the application opened the line is ignored. One common example is a voice call followed by a fax transmission in the same call. Directed handoff would most often be used by applications from the same developer that are linked in other ways as well.

Directed handoff may also be used in future versions as part of the process of arbitrating multiple applications waiting for incoming calls of the same media type, with the selection of the application to handle the call being based on data-link or higher-level protocol detection rather than media type. An example of its use would be an incoming data modem line with applications such as remote takeover, bulletin board, remote network access, and remote e-mail access all waiting for calls simultaneously.

Media Type Handoffs

A media type handoff takes place when there is a new, targeted media type, usually when the owning application determines that the media type needed for the call is not present or is about to change.

The process for a media-dependent handoff can be a probing process if the media type UNKNOWN bit is on. It is the responsibility of the owning application to cycle through media types to find the highest-priority application. TAPI does this cycling only on the initial incoming call to find the first owner. It does not do this for a handoff operation. Otherwise, a handoff is virtually the same as for the initial assignment of a call to an application. The difference is the fact that only one media type can be set for an indirect (media type) handoff.

Because only a single media type bit can be specified, the call is given to the highest priority application for that media type. However, it is possible that more than one media type is to be considered for the handoff. In this case, the handing-off application should specify the highest priority of the possible media types as a parameter.

If an application specifies the UNKNOWN bit when performing a media-type handoff and the handoff fails, this means that an unknown application capable of performing media type determination is not currently running. The application that is handing off should then try to hand the call off to the highest-priority application registered for the next-higher media type.

The receiving application is now responsible for the call. It now probes for the call's actual media type. If the application can handle the call's media type, it must ensure that it is the highest-priority application registered for that media type. If so, it keeps the call and processes it normally. If not, it hands the call off to another application registered for that media type.

If, however, the probe for that media type fails, the application probes again, attempting the remaining media-mode possibilities. It must first turn off the current media type bit, then try another handoff with a different type.

This process of probing and handing off continues, and the remaining media types are eliminated one by one. Along the way, one of the applications may see that the media type it handles is on the call, and the handoff is successful.

The application should then set the correct media type and clear all other media-type bits. This informs other interested applications of the correct media type. These other applications receive a an event notification message stating that the call's media type has changed.


Hold

The hold operation allows a single address to handle multiple communications sessions. Placing a session on a hard hold frees the user's line/address to make other calls. A call on hard hold typically cannot be transferred or included in a conference call, but a consultation call can. Consultation calls are initiated using conference or transfer operations.

After a call has been successfully placed on hold, the call state typically transitions to the onhold state. While a call is on hold, the application can receive messages about state changes of the held call. For example, if the held party hangs up, the call state can transition to disconnected.

In a bridged situation, the hold operation may not actually place the call on hold. The status of other stations on the call can govern (for example, attempting to "hold" a call when other stations are participating is not possible); instead, the call can simply be changed to the inactive state while it remains connected at other stations.

Not all service providers support use of this operation.

TAPI 2: lineHold, lineUnhold

TAPI 3: ITBasicCallControl::Hold


Park

The park operation allows an application to send a session to a special address where it will be held until unparked. From the point of view of the application, this looks much like a transfer. To the party on the other end of the connection, this resembles being put on hold.

The difference between park and transfer is that the parked address is not a connection point for the session, and the session does not alert or time out. The difference between park and hold is that once park operation completes, the session is no longer associated with the application's address.

Two forms of parking a session are provided: directed park and nondirected park. In directed call park, the application specifies the destination address where the call is to be parked. With nondirected park, the service provider or underlying hardware determines the address and returns it to the application.

A parked session typically enters the idle state after it has been successfully parked, and the application should then release the resources associated with it. See Terminate a Session for a summary of how to do this.

If the application unparks the session, new session resources are allocated even if the application has returned the previous pointers, so failure to do proper releases can result in a variety of problems.

Some service providers can remind the user after a session has been parked for some long amount of time. The application sees an offering call with a call reason set to reminder.

Not all service providers support use of this operation.

TAPI 2: linePark, lineUnpark

TAPI 3: ITBasicCallControl::ParkDirect, ITBasicCallControl::ParkIndirect, ITBasicCallControl::Unpark


Pickup

The pickup operation allows an application to answer a session that is alerting at another address. The application identifies the target of the pickup and is returned a session identifier for the picked-up call.

There are several ways to identify the target of the pickup request. First, the application may specify the address of the alerting party. Second, if no address is specified and the switch allows it, the application can pick up any alerting session in its pickup group. Third, some switches allow pickup of a session alerting in a different pickup group if the group identifier is specified.

Some key telephone systems support a transfer through hold capability on bridged-exclusive call appearances. In this scheme, a particular phone owns a call exclusively when the call is active, but when the call is on hold, any phone that has an appearance of the line can pick up the call.

In TAPI version 2.0 and later, an application can use a pickup operation with a NULL target address for this purpose, similar to how the function is used to pick up a call waiting call on an analog line. LINEADDRFEATURE_PICKUPHELD indicates the existence of the capability.

If LINEADDRCAPFLAGS_PICKUPCALLWAIT is TRUE, a session can be picked up for which the user has audibly detected the call-waiting signal but for which the service provider is unable to perform the detection. This gives the user a mechanism to "answer" a waiting call even though the service provider was unable to detect the call-waiting signal. Both the destination address and the group ID must be NULL to pick up a call-waiting call.

When a session has been picked up successfully, the application receives a state change notification with the reason set to LINECALLREASON_PICKUP.

Not all service providers support use of this operation.

TAPI 2: linePickup

TAPI 3: ITBasicCallControl::Pickup


Redirect

Session redirection allows an application to deflect an offered session to another address without answering the call. The application can do redirection on a call-by-call basis. For example, an application might allow a user to specify different redirections based on caller ID information. After a call has been successfully redirected, the state typically transitions to idle and associated resources must be released.

Redirect differs from forward in that once forwarding has been set up, the operation is performed by TAPI, the service provider, or the switch without further involvement of the application. Redirect differs from transfer in that redirect does not require answering the call first.

Not all service providers support use of this operation.

TAPI 2: lineRedirect


Secure a Session

If an application does not want any interference by outside events for a session from TAPI or the service provider, it should secure the call. For example, in an analog environment call-waiting tones can destroy a fax or modem session on the original call.

An application can secure a call at the time the call is made or after the call already exists.

Not all service providers support use of this operation.

TAPI 2: lineSecureCall

TAPI 3: ITAddress::Forward


Transfer

The transfer operation allows an application to send a currently connected communications session to a different address.

TAPI provides two mechanisms for transferring a current session to a different address. Blind transfer allows an existing session to be transferred to a specified destination address in one phase. Consultation transfer requires the existence of a consultation session in addition to the current session to set up for the transfer, and then completion of the transfer. The choice between these two types is frequently based on service provider capabilities because some service providers do not support blind transfer. In some cases, application needs may make the consultative transfer the preferred method even where blind transfer is possible.

The blind transfer operation is basically the same under TAPI 2 and TAPI 3, but consultative transfer follows slightly different patterns.

TAPI 2 consultative transfer starts with invoking lineSetupTransfer, which places the existing call on consultation hold, and identifies this call as the target for the next transfer-completion request. The lineSetupTransfer function also allocates a consultation call that can be used to establish the consultation call with the party to which the call will be transferred. The application can dial the extension of the destination party on the consultation call (using lineDial), or it can drop and deallocate the consultation call and instead activate an existing held call (using lineUnhold), if supported by the switch. While the initial call is on consultation hold and the consultation call is active, the application can toggle between these calls using lineSwapHold.

A TAPI 2 application completes the consultative transfer using lineCompleteTransfer. Both calls will revert to the idle state.

In TAPI version 2.0 and later, applications can use the "one-step transfer" feature of many PBXs (a single button press to establish a consultation transfer) by setting the lpCallParams parameter to the LINECALLPARAMFLAGS_ONESTEPTRANSFER member of the LINECALLPARAMFLAGS_ constants when calling lineSetupTransfer.

TAPI 3 consultative transfer starts with using ITAddress::CreateCall to create the consultation call to the new destination address. ITBasicCallControl::Transfer is used to set up the transfer. ITBasicCallControl::Finish completes the transfer.

The application must release session resources following the successful completion of a transfer operation.

Not all service providers support use of this operation.

TAPI 2: lineBlindTransfer, lineSetupTransfer, lineCompleteTransfer

TAPI 3: ITBasicCallControl::BlindTransfer, ITAddress::CreateCall, ITBasicCallControl::Transfer, ITBasicCallControl::Finish


Terminate a Session

Session termination may originate with a user request, remote disconnection by the other party, or for application-specific reasons. When a session is terminated, the session identifier remains valid until specifically released and can be used to gather post-connection data.

Session termination is completed by deallocating and releasing the resources associated with the session. If a session is merely dropped or disconnected but resources are not released, the result is a memory leak in the application and possibly in the service provider as well.

TAPI 2: lineDrop, lineDeallocateCall

TAPI 3: ITBasicCallControl::Disconnect, perform a standard COM release on the Call object pointer.


Session Information

TAPI applications must gather and process a variety of session information to function properly. For example, an answer operation fails unless the session is in the "offering" state.

TAPI 2 applications primarily use the lineGetCallInfo function to access session information. Additional functions which manipulate session information are lineGetCallStatus, lineSetCallParams, lineSetCallData, lineSetCallTreatment, lineSetCallPrivilege, lineGetCallStatus, and lineSendUserUserInfo.

TAPI 3 applications primarily use the ITCallInfo interface to access session information.

Information | TAPI 2 | TAPI 3
Address type for a session | lineGetCallInfo, dwAddressType member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_CALLERIDADDRESSTYPE, CIL_CALLEDIDADDRESSTYPE, or CIL_CONNECTEDIDADDRESSTYPE member of CALLINFO_LONG.
Application-specific information | lineGetCallInfo, dwAppSpecific member of LINECALLINFO lineSetAppSpecific | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_APPSPECIFIC member of CALLINFO_LONG.
Bearer mode | lineGetCallInfo, dwBearerMode member of LINECALLINFO lineSetCallParams | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_BEARERMODE member of CALLINFO_LONG.
Call data buffer | lineGetCallInfo, dwCallDataSize and dwCallDataOffset members of LINECALLINFO lineSetCallData | ITCallInfo::GetCallInfoBuffer, called with the CIB_CALLDATABUFFER member of CALLINFO_BUFFER
Call ID | lineGetCallInfo, dwCallID member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_CALLID member of CALLINFO_LONG.
Called Identification | lineGetCallInfo with dwCalledIDSize, dwCalledIDOffset, dwCalledIDNameSize, dwCalledIDNameOffset, and dwCallDataOffset members of LINECALLINFO | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_CALLINGPARTYID member of CALLINFO_STRING.
Called party friendly name | NA | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_CALLEDPARTYFRIENDLYNAME member of CALLINFO_STRING.
Caller Identification | lineGetCallInfo with dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, and dwCallerIDNameOffset, members of LINECALLINFO | ITCallInfo::get_CallInfoString, called with the CIS_CALLERIDNAME, CIS_CALLERIDNUMBER, CIS_CALLEDIDNAME, or CIS_CALLEDIDNUMBER member of CALLINFO_STRING.
CallHub interface pointer | NA | ITCallInfo::get_CallHub ITTAPI::EnumerateCallHubs
Charging information | lineGetCallInfo, dwChargingInfoSize and dwChargingInfoOffset members of LINECALLINFO. | ITCallInfo::GetCallInfoBuffer, called with the CIB_CHARGINGINFOBUFFER member of CALLINFO_BUFFER
Comment | lineGetCallInfo, dwCommentSize and dwCommentOffset members of LINECALLINFO. | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_COMMENT member of CALLINFO_STRING.
Compatibility buffer | lineGetCallInfo, dwHighLevelCompSize, dwHighLevelCompOffset, dwLowLevelCompSize, or dwLowLevelCompOffset members of LINECALLINFO. | ITCallInfo::GetCallInfoBuffer, called with the CIB_HIGHLEVELCOMPATIBILITYBUFFER or CIB_LOWLEVELCOMPATIBILITYBUFFER member of CALLINFO_BUFFER
Completion ID | lineGetCallInfo, dwCompletionID member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_COMPLETIONID member of CALLINFO_LONG.
Connected Identification | lineGetCallInfo, dwConnectedIDSize, dwConnectedIDOffset, dwConnectedIDNameSize, or dwConnectedIDNameOffset member of LINECALLINFO | ITCallInfo::get_CallInfoString, called with the CIS_CONNECTEDIDNAME or CIS_CONNECTEDIDNUMBER member of CALLINFO_STRING.
Country code | lineGetCallInfo,dwCountryCode member of LINECALLINFO | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_COUNTRYCODE member of CALLINFO_LONG.
Device-specific buffer | lineGetCallInfo, dwDevSpecificSize and dwDevSpecificOffset members of LINECALLINFO | ITCallInfo::GetCallInfoBuffer, called with the CIB_DEVSPECIFICBUFFER member of CALLINFO_BUFFER
Displayable address | lineGetCallInfo, dwDisplayableAddressSize and dwDisplayableAddressOffset members of LINECALLINFO | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_DISPLAYABLEADDRESS member of CALLINFO_STRING.
Media type for a session | lineGetCallInfo, dwMediaMode member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_MEDIATYPESAVAILABLE member of CALLINFO_LONG.
Origin | lineGetCallInfo, dwOrigin member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_ORIGIN member of CALLINFO_LONG.
Parameter flags | lineGetCallInfo, dwCallParamFlags member of LINECALLINFO lineSetCallParams | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_CALLPARAMSFLAGS member of CALLINFO_LONG.
Privilege | lineGetCallStatus,dwCallPrivilege member of LINECALLSTATUS lineSetCallPrivilege | ITCallInfo::get_Privilege or ITCallInfo::get_CallInfoLong, called with the CIL_NUMBEROFOWNERS or CIL_NUMBEROFMONITORS member of CALLINFO_LONG.
Quality of Service | lineSetCallQualityOfService, lineGetCallInfo, dwSendingFlowspecSize, dwSendingFlowspecOffset, dwReceivingFlowspecSize, and dwReceivingFlowspecOffset members of LINECALLPARAMS | ITBasicCallControl::SetQOS, ITQOSEvent
Rate | lineGetCallInfo, dwRate member of LINECALLINFO lineSetCallParams | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_MAXRATE, CIL_MINRATE, or CIL_RATE member of CALLINFO_LONG.
Reason | lineGetCallInfo, dwReason member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_REASON member of CALLINFO_LONG.
Redirect Identifcation | lineGetCallInfo, dwRedirectionIDSize, dwRedirectionIDOffset, dwRedirectionIDNameSize, dwRedirectionIDNameOffset, dwRedirectingIDSize, dwRedirectingIDOffset, dwRedirectingIDNameSize, or dwRedirectingIDNameOffset member of LINECALLINFO | ITCallInfo::get_CallInfoString called with the CIS_REDIRECTIONIDNAME, CIS_REDIRECTIONIDNUMBER, CIS_REDIRECTINGIDNAME, or CIS_REDIRECTINGIDNUMBER member of CALLINFO_STRING.
State | lineGetCallStatus,dwCallState member of LINECALLSTATUS. | ITCallInfo::get_CallState
Treatment | lineGetCallInfo, dwCallTreatment member of LINECALLINFO lineSetCallTreatment | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_CALLTREATMENT member of CALLINFO_LONG.
Trunk | lineGetCallInfo, dwTrunk member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_TRUNK member of CALLINFO_LONG.
User/user information | lineGetCallInfo, dwCallDataSize and dwCallDataOffset members of LINECALLINFO lineSendUserUserInfo | ITCallInfo::GetCallInfoBuffer, called with the CIB_USERUSERINFO member of CALLINFO_BUFFER and ITCallInfo::ReleaseUserUserInfo.


Address Type for a Session

The address type identifies the format required for an address. For example, if the type is LINEADDRESSTYPE_PHONENUMBER, the address used to dial on the session must be a phone number.

A given device and service provider supports one or more address types. See the address types for a device for information on how to poll a device for the address formats it supports.

TAPI 2: lineGetCallInfo, dwAddressType member of LINECALLINFO

TAPI 3: ITCallInfo::get_CallInfoLong, called with the CIL_CALLERIDADDRESSTYPE, CIL_CALLEDIDADDRESSTYPE, or CIL_CONNECTEDIDADDRESSTYPE member of CALLINFO_LONG


Application-specific Information

Application-specific information allows applications to pass each other information concerning a session through TAPI. This information is not interpreted by TAPI and usage is entirely defined by the applications.

When application-specific information is changed by one application, TAPI sends all other applications with monitor or owner privileges on the session an event indicating that a change has occurred.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwAppSpecific member of lpCallInfo), lineSetAppSpecific, LINE_CALLINFO message (dwParam1 set to LINECALLINFOSTATE_APPSPECIFIC)

TAPI 3: ITCallInfo::get_CallInfoLong, ITCallInfo::put_CallInfoLong (CIL_APPSPECIFIC member of CALLINFO_LONG)


Bearer Mode

The bearer mode corresponds to the quality of transmission requested from the network for establishing a call. It is important to keep the concept of bearer mode separate from that of media type. As an example, the analog telephone network (PSTN) provides only a 3.1 kHz voice-grade bearer mode but calls using it can support media types such as voice, fax, or data modem.

The bearer mode of a call is specified when the call is set up, or is provided when the call is offered. With line devices able to represent channel pools, it is possible for a service provider to allow calls to be established with wider bandwidth.

Not all service providers support use of this information.

TAPI 2: lineSetCallParams, lineGetCallInfo, dwBearerMode member of LINECALLINFO

TAPI 3: ITCallInfo::get_CallInfoLong, ITCallInfo::put_CallInfoLong, CIL_BEARERMODE member of CALLINFO_LONG

TSPI: LINE_CALLINFO message, with dwParam1 set to LINECALLINFOSTATE_BEARERMODE


Call Data

Call data is a variably sized buffer that can be used to accumulate information about a communications session. This information becomes available to all applications that own or monitor the session.

For example, the initial handler of an incoming session might request and enter client account information into a call data buffer, and then subsequent handlers would not have to repeat the request.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo, lineSetCallData (dwCallDataSize and dwCallDataOffset members of LINECALLINFO), LINE_CALLINFO message (dwParam1 set to LINECALLINFOSTATE_CALLDATA)

TAPI 3: ITCallInfo::get_CallInfoBuffer,

ITCallInfo::put_CallInfoBuffer (CIL_CALLDATABUFFER member of CALLINFO_LONG), ITCallInfoChangeEvent::get_Cause returns the CIC_CALLDATA member of CALLINFOCHANGE_CAUSE


Call ID

The Call ID differs from the Session Identifier in two primary ways: the service provider assigns it, and it is the same for every application that handles the session. It cannot be used for ordinary communication with TAPI concerning session operations because it does not match to a particular application.

The Call ID is used in operations such as determining whether a group of session IDs actually refer to one call, as is the case for a conference, or for communications with another application.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwCallID member of LINECALLINFO)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_CALLID member of CALLINFO_LONG)


Caller Identification

Caller identification provides information on the calling party when receiving an incoming session. An application typically uses this data as part of a status message to a user.

This information is not always available immediately. An application that wants to use this information and has verified that the service provider supports it should check several times before assuming that the information is not available.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwCallerIDFlags, dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, dwCallerIDNameOffset, and dwCallerIDAddressType members of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_CALLERIDADDRESSTYPE member of CALLINFO_LONG), ITCallInfo::get_CallInfoString (CIS_CALLERIDNAME and CIS_CALLERIDNAME members of CALLINFO_STRING)


Called Identification

Called identification identifies the original destination address for a session. In situations where a session was redirected, forwarded, or transferred, this will be different than the connected identification.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwCalledIDFlags, dwCalledIDSize, dwCalledIDOffset, dwCalledIDNameSize, dwCalledIDNameOffset, and dwCalledIDAddressType members of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_CALLEDIDADDRESSTYPE member of CALLINFO_LONG), ITCallInfo::get_CallInfoString (CIS_CALLEDIDNAME and CIS_CALLEDIDNAME members of CALLINFO_STRING)


Charging Information

Charging information is specific to the ISDN Q.931 standard. Please refer to your service provider's documentation on the meaning and use of this data.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwChargingInfoSize and dwChargingInfoOffset members of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoBuffer (CIB_CHARGINGINFOBUFFER member of CALLINFO_BUFFER)


Comment

An application can set a comment during the initiation of a session. Comments are often used for logging purposes.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwCommentSize and dwCommentOffset members of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoString (CIL_COMMENT member of CALLINFO_STRING)


Compatibility Buffer

The compatibility buffer is specific to the ISDN Q.931 standard. Please refer to your service provider's documentation on the meaning and use of this data.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwHighLevelCompSize, dwHighLevelCompOffset, dwLowLevelCompSize, and dwLowLevelCompOffset members of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoBuffer (CIB_HIGHLEVELCOMPATIBILITYBUFFER and CIB_LOWLEVELCOMPATIBILITYBUFFER member of CALLINFO_BUFFER)


Completion ID

The completion identifier for the incoming call is the result of a completion request that terminates.

TAPI 2: lineGetCallInfo (dwCompletionID member of the LINECALLINFO structure pointed to by lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_COMPLETIONID member of CALLINFO_LONG)


Connected Identification

The connected identification identifies the party that was actually connected to. This may be different from the called identification if the call was diverted.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwConnectedIDFlags, dwConnectedIDSize, dwConnectedIDOffset, dwConnectedIDNameSize, and dwConnectedIDNameOffset members of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoString (CIL_CONNECTEDIDNAME member of CALLINFO_STRING)


Country Code

The country code is relevant only when the address type is LINEADDRESSTYPE_PHONENUMBER. It identifies an area of the world.

All service providers that support use of telephone numbers must support use of this information.

TAPI 2: lineGetCallInfo (dwCountryCode member of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_COUNTRYCODE member of CALLINFO_LONG)


Device-specific Buffer

Device-specific buffers may be part of a service provider's implementation of extended operations. The service provider defines the meaning of these buffers.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo, dwDevSpecificSize and dwDevSpecificOffset members of LINECALLINFO

TAPI 3: ITCallInfo::GetCallInfoBuffer, called with CIB_DEVSPECIFICBUFFER member of CALLINFO_BUFFER


Displayable Address

The displayable address is a string that presents the address in a form that is suitable for display in a user interface.

TAPI 2: lineGetCallInfo, dwDisplayableAddressSize and dwDisplayableAddressOffset members of LINECALLINFO

TAPI 3: ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_DISPLAYABLEADDRESS member of CALLINFO_STRING


Media Type for a Session

The media type (or mode) describes the type of information being exchanged, such as interactive voice. A given communications session may involve several media types.

Service providers expose to TAPI and to applications the media type or types they support. See the device media type overview for information on acquiring this data.

TAPI 2: lineGetCallInfo, lineSetMediaMode, lineMonitorMedia, LINE_MONITORMEDIA message, LINEMEDIAMODE_ Constants

TAPI 3: ITCallInfo::get_CallInfoLong with CIL_MEDIATYPESAVAILABLE, ITCallInfo::put_CallInfoLong with CIL_MEDIATYPESAVAILABLE, ITCallInfoChangeEvent::get_Cause returns CALLINFOCHANGE_CAUSE of CIC_MEDIATYPE, TAPIMEDIATYPE_ Constants


Origin

Origin is a general description of where the session started, such as whether it is external or internal to a corporate network. See LINECALLORIGIN_ Constants for a listing of origins that TAPI supports.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwOrigin member of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_ORIGIN member of CALLINFO_LONG)


Parameter Flags

Parameter flags supply information on a variety of status flags concerning a communications session, such as whether caller identification should be blocked. See LINECALLPARAMFLAGS_ Constants for a list of flags defined by TAPI.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwCallParamFlags member of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_CALLPARAMSFLAGS member of CALLINFO_LONG)


Privilege

Privilege refers to whether an application owns or is monitoring the session. If the application owns the session, it is allowed to perform a variety of session operations. If the application is only monitoring, it will receive state messages and it can access session information, but any attempt to perform most operations will result in an error.

During initialization, an application tells TAPI which privilege level it requires on which addresses. TAPI offers incoming sessions only to applications that have registered for either owner or owner and monitor privilege.

An application's privilege on a session it creates is always owner.

TAPI 2: lineGetCallStatus, dwCallPrivilege member of LINECALLSTATUS, lineSetCallPrivilege

TAPI 3: ITCallInfo::get_Privilege, ITCallInfo::get_CallInfoLong, called with the CIL_NUMBEROFOWNERS or CIL_NUMBEROFMONITORS member of CALLINFO_LONG


Quality of Service

Asynchronous Transfer Mode (ATM) networking is emerging into the mainstream of computing, and support for ATM has been added to many parts of the Microsoft® Windows® operating system. TAPI also supports key attributes of establishing calls on ATM facilities. The most important of these from an application perspective is the ability to request, negotiate, renegotiate, and receive indications of Quality of Service (QOS) parameters on incoming and outgoing calls.

QOS information in TAPI is exchanged between applications and service providers in FLOWSPEC structures that are defined in Windows Sockets 2.0.

Applications request QOS on outgoing calls by setting session information values prior to starting a communications session. The service provider will try to provide the specified QOS, and fail the call if it cannot. The application can then adjust its parameters and try the call again. After a call is established, an application can request a change in the QOS.

TAPI provides event notifications to owner or monitor applications if there is any change in QoS levels.

Support for QOS is not restricted to ATM transports; any service provider can implement QOS features.

Not all service providers support use of this information.

TAPI 2: lineSetCallQualityOfService, lineGetCallInfo, dwSendingFlowspecSize, dwSendingFlowspecOffset, dwReceivingFlowspecSize, and dwReceivingFlowspecOffset members of LINECALLPARAMS

TAPI 3: ITBasicCallControl::SetQOS, ITQOSEvent


Rate

The rate (or bandwidth) of a call specifies the speed of data transmission. Three data points identify rate: the current rate, the maximum rate for a specified bearer mode, and the minimum rate for the bearer mode.

Not all service providers support use of this information.

TAPI 2: lineSetCallParams, lineGetCallInfo, dwMinRate or dwMaxRate member of LINECALLINFO

TAPI 3: ITCallInfo::get_CallInfoLong, ITCallInfo::put_CallInfoLong, CIL_MAXRATE, CIL_MINRATE, or CIL_RATE member of CALLINFO_LONG

TSPI: LINE_CALLINFO message, with dwParam1 set to LINECALLINFOSTATE_RATE


Reason

The possible reasons for an incoming session, such as that it was transferred, are listed in the LINECALLREASON_ Constants.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwReason member of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_REASON member of CALLINFO_LONG)


Redirect Identification_ovr

Platform SDK: TAPI

Redirect Identification

When an application redirects a session, TAPI retains identification information about the location that redirected the session and the location to which it was redirected.

"Redirecting" refers to the location that invoked the redirect operation. "Redirection" identifies the new destination for the session.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo, dwRedirectionIDSize, dwRedirectionIDOffset, dwRedirectionIDNameSize, dwRedirectionIDNameOffset, dwRedirectingIDSize, dwRedirectingIDOffset, dwRedirectingIDNameSize, and dwRedirectingIDNameOffset members of LINECALLINFO

TAPI 3: ITCallInfo::get_CallInfoString called with the CIS_REDIRECTIONIDNAME, CIS_REDIRECTIONIDNUMBER, CIS_REDIRECTINGIDNAME, or CIS_REDIRECTINGIDNUMBER member of CALLINFO_STRING


Session Identifier

TAPI assigns session identifiers that are unique for each session and application. An application uses a session identifier to communicate with TAPI concerning a specific session. An application typically obtains an identifier either by creating a new communications session or when TAPI offers a session.

A session identifier cannot be used to pass information to another application. For this purpose, use the Call ID, which may be assigned by a service provider.

See Initiate a session for information on operations that create sessions and return a session identifier. See Respond to session initiated elsewhere for operations that acquire session identifiers from TAPI. See Terminate a Session for information on releasing session resources.

All service providers must support some form of session identification.

Under TAPI 2, the primary identifier of a communications session is the call handle.

For TAPI 3, a session is represented by a Call Object and the primary identifier is a pointer to the ITCallInfo interface.


State

Session or call state indicates the current status of a session, such as "offering" or "connected." Proper handling of state information is vital to the proper functioning of most TAPI applications. For example, the answer operation can be performed only on an offered session, but a transfer will fail if the session is in that state.

A session's state changes as a result of events. Events can be solicited or unsolicited. Solicited events are caused by the application controlling the session, such as when it invokes a TAPI session operation. Unsolicited events are caused by the switch, the telephone network, the user pressing buttons on the local phone, or the actions of the remote party.

Whenever a service provider detects a session state change, it reports the change to TAPI and TAPI issues an event notification to all owner and monitor applications. The application must react to these notifications appropriately. Please see Event Notification under TAPI Initialization for information on controlling which events are reported to an application.

An application should always process state event notifications. State transitions valid for one physical configuration may be invalid for another. For example, consider a line that physically terminates both at the computer and at a separate phone set, creating a party line configuration between the computer and the phone set. An application running on the computer may not know about phone set activities. That is, the line may be in use without the service provider being aware of it. An application that attempts to make an outgoing call will succeed in allocating a call appearance from TAPI, but this results in sharing the active call on the line. Blindly sending a DTMF dial string without first checking for a dial tone may not result in intended (or polite) behavior.

An application should not assume a rigid progression from one state to another. State events arrive and are forwarded asynchronously and notifications may not be received in a predictable order. Therefore, call-state notifications should be viewed as telling the application the call's new state instead of as reporting the transitions between two states.

All telephony service providers must supply this information.

TAPI 2: lineGetCallStatus, lineGetCallInfo, LINE_CALLSTATE message, LINECALLSTATE_ Constants

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_CALLID member of CALLINFO_LONG), ITCallStateEvent notification, CALL_STATE enumerator


Treatment

Treatment refers to the handling of an incoming session that has not yet been answered or has been put on hold, such as music. Please see LINECALLTREATMENT_ Constants for a list of treatments defined by TAPI.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo (dwCallTreatment member of lpCallInfo)

TAPI 3: ITCallInfo::get_CallInfoLong (CIL_CALLTREATMENT member of CALLINFO_LONG)


Trunk

The number of the trunk over which the call is routed. This member is used for both incoming and outgoing calls.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo, dwTrunk of LINECALLINFO

TAPI 3: ITCallInfo::get_CallInfoLong, called with CIL_TRUNK member of CALLINFO_LONG


User-user information

User-user information is a buffer that can be transmitted from one end of a connection to another. This information is specific to the ISDN Q.931 standard. Please refer to your service provider's documentation on the meaning and use of this data.

Not all service providers support use of this information.

TAPI 2: lineGetCallInfo, dwCallDataSize and dwCallDataOffset members of LINECALLINFO, lineSendUserUserInfo

TAPI 3: ITCallInfo::GetCallInfoBuffer, called with the CIB_USERUSERINFO member of CALLINFO_BUFFER, ITCallInfo::ReleaseUserUserInfo


Media Control

The media of a communications session is the form in which the data is transmitted. Media controls allow an application to recognize a variety of media types and adjust aspects of the media stream, such as the volume of voice transmission.

The availability of media control and information varies widely with the type of TAPI application, service provider support, and the local communications environment. The following material provides a general description of media control. TAPI supplies a flexible framework for the implementation of controls, so the most interesting capabilities will often be specific to a given service provider.

Under classic telephony, an application had very little control over the media stream once a communications path had been set up. TAPI 2 applications have access to some functions that allow them to recognize and react to digits or tones during a call, and they may be able to use the Wave API to exercise additional control over media during a communications session, but otherwise they do not have media stream access. See the TAPI 2.2 Media Access overview or the TSPI Media Access overview for a review of these functions.

TAPI 3.0 introduces the Media Service Providers, which steeply increases both information about and control over the media or a communication session. A TAPI 3 application can directly access the media stream of a session. A separate stream is created for each media type involved in the session, such as voice or video. Some MSPs may implement substream controls, which can divide streams further, such as by participant in the case of the IPConf MSP.

TAPI 2 functions | Description
lineGatherDigits | Initiates the buffered gathering of digits on the specified call.
lineGenerateDigits | Initiates the generation of the specified digits on the specified call as inband tones using the specified signaling mode.
lineGenerateTone | Generates the specified inband tone over the specified call.
lineMonitorDigits | Enables and disables the unbuffered detection of digits received on the call.
lineMonitorMedia | Enables and disables the detection of media types on the specified call.
lineMonitorTones | Enables and disables the detection of inband tones on the call.
lineSetMediaControl | Enables and disables control actions on the media stream associated with the specified line, address, or call.

TAPI 3 interfaces or methods | Description
ITLegacyCallMediaControl | Supports legacy applications that must communicate directly with a device.
ITLegacyWaveSupport | Allows an application to discover whether a terminal created by a legacy TSP (pre-TAPI 3) can be controlled using the Win32 Wave API.
ITStream | Allows an application to retrieve information on a stream; to start, pause, or stop the stream; to select or unselect terminals on a stream; and to obtain a list of terminals selected on the stream.
ITStreamControl | Allows an application to enumerate, create, or remove media streams.


TAPI Shutdown

Proper shutdown of communications sessions and of an entire application is required to prevent resources from remaining tied up in calls or applications that no longer need them.

TAPI provides a series of functions and methods to assist in the process. Obviously, the application must also take responsibility for properly releasing allocated memory, whether in the form of data structures or COM references.

TAPI 2 functions | Description
lineRegisterRequestRecipient | Unregisters the application as a handler for assisted telephony calls.
lineClose | Disconnects the application as a manager for calls on the given line.
lineShutdown | Shuts down the application's usage of the line abstraction.

TAPI 3 interfaces or methods | Description
ITTAPI::UnregisterNotifications | Removes any event notification registrations performed by the application.
ITTAPI::Shutdown | Disconnects the application as a call manager.


TAPI DLL

The TAPI DLLs, along with the TAPI Server (Tapisvr.exe), are crucial abstractions separating end-user or server applications from service providers. A TAPI DLL in conjunction with the TAPI Server provides a consistent interface between these two layers.

A TAPI application loads the appropriate DLL into its process space. During initialization, TAPI establishes an RPC link with Tapisvr.exe. The TAPI Server runs as a separate service on Windows 9x and Windows NT. On Windows 2000, the TAPI Server runs in the context of SVCHOST.

There are three DLLs associate with TAPI: Tapi.dll, Tapi32.dll, and Tapi3.dll. The following figure illustrates the roles of their respective roles in Microsoft Telephony:

Existing 16-bit applications link to Tapi.dll. In Windows 3.1 and Windows 95, this DLL is the core of Windows Telephony. Under Windows 98 and Windows NT/Windows 2000, Tapi.dll is simply a thunk layer to map 16-bit addresses to 32-bit addresses and pass requests to Tapi32.dll.

Existing 32-bit TAPI 2 applications link to Tapi32.dll. In Windows 95, Tapi32.dll is a thunk layer to Tapi.dll. In Windows 98 and Windows NT/Windows 2000, Tapi32.dll is a thin marshaling layer that transfers function requests to the TAPI Server (Tapisrv.exe) and, when needed, loads and invokes media service provider DLLs in the application's process.

TAPI 3 applications link to Tapi3.dll.


The TAPI Server

The TAPI server (Tapisrv.exe) is the central repository of telephony information on a user machine. This service process tracks local and remote telephony resources, applications registered to handle Assisted Telephony requests, and pending asynchronous functions, and it also enables a consistent interface with telephony service providers (TSPs). Please see The Microsoft Telephony Programming Model for a diagram illustrating the relationship of the TAPI Server to other components and an overview of their roles.

On Windows 95, Windows 98, and Windows NT, Tapisrv.exe runs as a separate service process. On Windows 2000, it runs within the context of Svchost.exe. When an application loads a TAPI DLL into its process space and performs an initialization operation, the DLL establishes an RPC link to the TAPI Server. The TAPI Server loads telephone service providers (TSPs) into its process space. Regardless of how many applications access a given provider's devices, only one instance of a given TSP will exist.


The Service Providers

Service providers implement detailed telephony device controls. A telephony service provider (TSP) provides call controls and a media service provider, if it exists, provides control over the media stream.

All telephony service providers execute in the Tapisrv.exe process. Service providers can create threads in the TAPISRV context as needed to do their work, and be confident that none of the resources they create will be destroyed by the exit of any individual application. The TAPI Server translates application commands as needed into a consistent set of commands known as the Telephony Service Provider Interface (TSPI).

Media service providers execute in the process space of the application, allowing for the fast response sometimes required in media controls. The TAPI DLL provides for consistent adherence to the Media Service Provider Interface (MSPI).

For more detailed coverage of the service providers, please see TAPI Service Provider Overview.

Underneath the telephony service provider DLL, the service provider can use any system functions or other components necessary. These functions include CreateFile and DeviceIoControl, which work with independent hardware vendor-designed kernel mode components and services, as well as standard devices such as serial and parallel ports to control external, locally attached devices. They can also access network services (such as RPC, Windows Sockets, and Named Pipes) for client/server telephony.

The Telephony service provider user interface DLL is loaded by TAPI into the process of an application that invokes any of the service provider functions that can display a dialog box (for example, TSPI_lineConfigDialog). The service provider can also cause its associated UI DLL to be loaded and executed in the process of an application if the service provider needs to display UI at unexpected times, such as to display the Talk/Hang-up dialog box displayed by the Universal Modem Driver (UNIMODEM) when a data modem is used to dial an interactive voice call using TSPI_lineMakeCall (not normally considered to be a UI-generating function).

The proxy request handler is a full telephony application that normally executes on a telephony server (the same server on which the telephony service provider is executing for the associated line devices). This architecture, rather than the WOSA service provider architecture, is used when a particular service is more appropriately implemented in an application than in a driver on the server. For example, the ACD Agent management functions are implemented in a proxy request handler rather than in a service provider.

The UNIMODEM driver service provider for modem control is available on Windows NT/Windows 2000. Windows Telephony for Windows NT/Windows 2000 also includes a generic kernel-mode Telephony Service Provider Interface (TSPI) mapper, KMDDSP, that allows service providers to be implemented as kernel-mode device drivers.


General Programming Considerations

This section covers Microsoft Telephony programming considerations that apply to both end-user applications and service providers:

  • The Synchronous/Asynchronous Model
  • Data Structures Overview
  • TAPI Levels of Service


The Synchronous/Asynchronous Model

Telephony operations complete either synchronously or asynchronously. These two models differ as follows. Synchronous functions execute the entire request before the caller's thread is allowed to return from the function call. Asynchronous functions return from the function call before the request has executed in its entirety. When the asynchronous request later completes, the service provider reports the completion by calling a callback procedure that TAPI originally supplied to it early in the initialization sequence.

  • Asynchronous operations have a parameter named dwRequestID of the defined type DRV_REQUESTID as their first parameter. Such an operation performs part of its processing in the function call and the remainder of its processing in an independent execution thread after the function call has returned. When the function returns, it returns either a negative error result or the (positive) dwRequestID that was passed in the function call. The negative error result indicates that the operation is complete (and failed). The positive dwRequestID returned indicates that the operation continues in the independent thread. In such a case, the service provider eventually calls the ASYNC_COMPLETION procedure, passing the dwRequestID and a result code to indicate the outcome of the operation. The result code is zero for success or one of the same set of (negative) error results. In any case, the service provider must never return zero or any positive value other than dwRequestID from a function designated as asynchronous because doing so can produce unexpected results. Service providers should always copy input data from application memory into service provider memory before returning from an asynchronous function.
  • Synchronous operations do not have dwRequestID as their first parameter. Such an operation performs all of its processing in the caller's execution thread, returning the final result when it returns. The result is zero for success or a negative error code for failure. The service provider does not call ASYNC_COMPLETION for synchronous operations.

It is interesting to consider the timing of a "completion" callback relative to when the original request returns. A typical asynchronous request would be implemented by the service provider as in the following pseudocode:

Some_request(Request_ID, ...) {
  check parameters for validity
  check device state for validity
  store Request_ID for Completion Interrupt Handler's use
  manipulate device registers to start physical operation
  return Request_ID  // to indicate asynch operation
}
Operation Completion Interrupt Handler: {
  if operation was successful then
    call "completion" callback passing Request_ID and "success"
  else
    call "completion" callback passing Request_ID and "error num"
  endif
}

If the operation completes very rapidly (or the original request returns very slowly), it is possible that the interrupt handler that runs when a physical operation completes may be triggered before the original request returns to the application or even to TAPI. This behavior is allowed. TAPI guarantees that the eventual completion notification to the application is delivered after the original request returns.


The Meaning of SUCCESS

When an operation returns a SUCCESS indication (either synchronously upon function return for synchronous operations, or asynchronously with a call to the ASYNC_COMPLETION callback procedure for asynchronous operations), then the following are assumed to be true:

  • The function has successfully progressed up to a service-provider-defined point. The service provider defines the point on a function-by-function basis. After reaching that point, either the operation is completely finished, or it is in a state such that subsequent independent state messages will inform the application about progress.
  • Functions that return information (such as TSPI_linePark or TSPI_lineDevSpecific) return SUCCESS only when the requested information is available to the caller. Functions that return handles (to opened lines, opened phones, or calls) return the handles immediately on function return. Both the service provider and the caller must treat the handles as "not yet valid" until the eventual SUCCESS indication. The service provider is responsible for preventing any callback messages to the LINEEVENT or PHONEEVENT procedure about that opened line, opened phone, or call until after the SUCCESS indication. If the eventual result is an error, any handle returned immediately becomes invalid without any further action.
  • Functions that enable certain permanent conditions (like TSPI_lineMonitorDigits) return SUCCESS only after the condition is enabled, not when the condition is removed again (for example, not when digit monitoring is complete).
  • Call control functions (such as TSPI_lineHold and TSPI_lineSetupTransfer, but not TSPI_lineMakeCall) return SUCCESS when the operation is completed. In telephony environments that do not provide positive acknowledgment of these functions, the service provider is forced to make a best-effort decision as to the success or failure of the function.
  • A service provider's implementation of TSPI_lineMakeCall must return SUCCESS no later than when the call enters the proceeding call state. Ideally, the provider indicates SUCCESS as soon as possible, such as when the call enters the dialtone call state (if applicable). When SUCCESS is returned to the application, LINE_CALLSTATE messages inform the caller about the progress of the call. Service providers that delay returning the TSPI_lineMakeCall SUCCESS indication, for example, until after dialing is complete, severely limit flexibility at the application level. Delay in returning SUCCESS in TSPI_lineMakeCall prevents a user from canceling the call setup request in progress until after dialing is complete, and all digits are sent to the switch.


Synchronous Requests

Service provider designers should try to keep the execution time of synchronous operations short. For example, there is an "Open" operation called at initialization time that prepares the service provider and TAPI for subsequent operations on a device. A service provider whose implementation is split between the client computer and a dedicated server may have reasonable confidence that it can communicate with its remote server. Its implementation of "Open" might just allocate and initialize data structures to represent the device and return, postponing end-to-end communication until some real operation is requested.

Any such "optimistic" implementation of a synchronous operation can later encounter resource limitations or remote communication failures. In general, even a "conservative" approach cannot entirely prevent these problems; service-provider designers must choose the best tradeoff between reliability and performance. A failure of this kind should be handled gracefully wherever possible. From the point of view of TSPI devices, they should remain valid for "bookkeeping" purposes even if they return failure status for any operation requested.

Implementing an optimistic approach for synchronous requests should not be done at the expense of correct semantics for the operation. Returning to the "Open" example, if opening a device needs to compete for and reserve a scarce, nonsharable resource such as communication ports, it should probably do so even if it is time-consuming.


Asynchronous Spontaneous Events

There is another class of asynchronous events besides those described above. These events are "spontaneous" in the sense that they are not direct results of corresponding requests. These events are detected in such cases as when an incoming call arrives, or when an outbound call goes from a "ringing" to an "answering" state. When TAPI first initializes interactions with the TSPI for a particular device, it passes a pointer to a callback procedure to be called for reporting such spontaneous events. Along with this procedure pointer is a device handle that the service provider includes as one of the actual parameters to the callback.


Call-less Asynchronous Operations

There are five asynchronous operations that are not related to any particular call. The TAPI 2 lineDevSpecific, lineDevSpecificFeature, lineForward, lineSetTerminal, and lineUncompleteCall functions initiate these operations. If an application initiates one of these asynchronous operations and calls lineClose, the service provider may receive no indication that the application has abandoned the function. This can occur if the application was not the only application to have the line open. If the application calls lineClose with one of these operations pending, and it is the only application with a handle to the line, TAPI calls the TSPI_lineClose function and the service provider should terminate the asynchronous operation, calling the ASYNC_COMPLETION callback function for each such outstanding operation with the LINEERR_OPERATIONFAILED error value.


Termination of Asynchronous Operations

When an application calls the lineClose function with one or more outstanding asynchronous operations, TAPI may direct the service provider to terminate asynchronous operations associated with a call, depending on whether the application is the sole owner of the call and has the only handle to the call.

If the application is the sole owner of a call, TAPI calls TSPI_lineDropOnClose or TSPI_lineDrop (depending on the provider) for each such call. The service provider should check for any pending asynchronous operations associated with the call being dropped. If a pending operation exists, the service provider should take the appropriate action, possibly terminating the operation in progress.

If the application has the only handle to a call (that is, there are no other owners or monitors), TAPI calls the TSPI_lineCloseCall function. The service provider must consider this call to be the absolute indication that pending asynchronous operations must be abandoned. The service provider must ensure an orderly completion of the call, and must call the ASYNC_COMPLETION callback function for all outstanding asynchronous operations, specifying the LINEERR_OPERATIONFAILED error value. If TAPI previously called the TSPI_lineDropOnClose or TSPI_lineDrop function, it calls TSPI_lineCloseCall immediately after the service provider returns from the other call; it does not wait for the asynchronous operation associated with the TSPI_lineDrop function to complete.

If the application is not the sole owner of the call, TAPI does not call TSPI_lineDropOnClose or TSPI_lineDrop. If the application does not have the only handle to the call, TAPI does not call the TSPI_lineCloseCall function. If the application is neither the sole owner nor the sole possessor of a handle to the call, TAPI sends no notification to the service provider, and therefore, any pending asynchronous operations remain intact. This means that such applications cannot terminate asynchronous operations that they have started by using the lineClose function. However, because every asynchronous operation requires the invoking application to be an owner of the call, the likelihood of an application not being able to terminate asynchronous operations is very rare. If it does occur, the other owner(s) of the call(s) must take responsibility for the disposition of the call(s).

If TAPI calls TSPI_lineDropOnClose or TSPI_lineDrop, the service provider must eventually send a LINECALLSTATE_IDLE message for the associated call (unless TSPI_lineCloseCall is called first) so that monitors on the call can clean up. When the last monitor has called the lineDeallocateCall function, TAPI calls the TSPI_lineCloseCall function; any pending operations must be completed or terminated and ASYNC_COMPLETION called, as described earlier.


Data Structures Overview

TAPI applications, TAPI, and telephony service providers use structures to receive and return the data associated with communications needs. This section discusses the following topics on how to use line device, phone device, and call center structures.

  • Memory Allocation
  • Variably Sized Data Structures
  • Extensibility


Memory Allocation

Applications are responsible for allocating memory for this information; TAPI and the service provider simply fill in the data. If the operation is asynchronous, then the information is not available until the asynchronous reply message indicates success.

All data structures used to pass information between the application and the TAPI are flattened. This means that data structures do not contain pointers to substructures that contain variably sized components of information. Instead, data structures that are used to pass variable amounts of information back to the application have the following metastructure:

  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
    <fixed size fields>
  DWORD  dw<VarSizeField1>Size;
  DWORD  dw<VarSizeField1>Offset;
    <fixed size fields>
  DWORD  dw<VarSizeField2>Size;
  DWORD  dw<VarSizeField2>Offset;
    <common extensions>
    <var sized field1>
    <var sized field2>

The dwTotalSize member is the size, in bytes, allocated to this data structure. It marks the end of the data structure and is set by the application before it invokes the function that uses this data structure. The function does not read or write beyond this size. An application must set the dwTotalSize member to indicate the total number of bytes allocated for TAPI to return the contents of the structure.

TAPI fills in the dwNeededSize member. It indicates how many bytes are needed to return all the information requested. The existence of variably sized fields often makes it impossible for the application to estimate the data structure size it needs to allocate. This field simply returns the number of bytes actually needed for the information. This number could be smaller than, equal to, or larger than dwTotalSize, and it includes space for the dwTotalSize member itself. If larger, the returned structure is only partially filled. If the fields the application is interested in are available in the partial structure, nothing else must be done. Otherwise, the application should allocate a structure at least the size of dwNeededSize and invoke the function again. Usually, enough space is available this time to return all the information, although it is possible the size could have increased again.

TAPI fills in the dwUsedSize member if it returns information to the application to indicate the actual size in bytes of the portion of the data structure that contains useful information. If, for example, a structure that was allocated was too small and the truncated field is a variably sized field, dwNeededSize is larger than dwTotalSize, and the truncated field is left empty. The dwUsedSize member could therefore be smaller than dwTotalSize. Partial field values are not returned.

Following this header is the fixed part of the data structure. It contains regular fields and size/offset pairs that describe the actual variably sized fields. The offset field contains the offset in bytes of the variably sized field from the beginning of the record. The size field contains the size in bytes of the variably sized field. If a variably sized field is empty, then the size field is zero and the offset is set to zero. Variably sized fields that would be truncated if the total structure size is insufficient are left empty. That is, their size field is set to zero and the offset is set to zero. The variably sized fields follow the fixed fields.

If the service provider is responsible for filling in a variable member, TAPI initializes the corresponding size and offset members to zero. If the service provider fills in the variable member, it must set the corresponding size and offset members to appropriate values, including dwUsedSize and dwNeededSize if it sets variable members. The service provider must not truncate a variable member to make it fit into the available space.

The service provider must start variable members immediately after the fixed members of the structure, and leave any extra space at the end of the allocated memory so that TAPI can use it for the variable-length members for which it is responsible. It can place the variable members in any order, but the members must be contiguous.


Variably Sized Data Structures

When variably sized data structures are used to transmit information between TAPI and the application, the application is responsible for allocating the necessary memory. The amount of memory allocated must be at least large enough for the fixed portion of the data structure, and is set by the application in the dwTotalSize member of the data structure. The dwUsedSize and dwNeededSize members are filled in by TAPI. If dwTotalSize is less than the size of the fixed portion, then LINEERR/ PHONEERR_STRUCTURETOOSMALL is returned. If a function returns success, then all the fields in the fixed portion have been filled in. The dwUsedSize and dwNeededSize members can be compared to determine if all variable parts have been filled in, and how much space would be required to fill them all in.

If dwNeededSize is equal to dwUsedSize, then all fixed and variable parts have been filled in. If dwNeededSize is larger than dwUsedSize, some variable parts may have been filled in, but exactly which variably sized fields have been filled in is undefined. No variable part is ever truncated, and variable parts that would have been truncated due to insufficient space are indicated by having both of their corresponding "Offset" and "Size" parts set to zero. If these are not both zero (and no error was returned), they indicate the offset and size of valid, nontruncated variable-part data.

An application can always guarantee that all variable parts are filled in by allocating and indicating dwNeededSize bytes for the structure and calling the "Get" function again until the function returns success and dwNeededSize equals dwUsedSize. This should happen on the second try except for race conditions that cause changes in the size of variable parts between calls, which should be a rare occurrence.

Note All text strings, regardless of encoding, in variably sized structures should be NULL-terminated according to normal C string-handling conventions.


Extensibility

Provisions are made for extending constants and structures both in a device-independent way and in a device-specific (vendor-specific) way. In constants that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values are identified as device specific. A vendor can define meanings for these values in any way desired. Their interpretation is keyed to the extension identifier provided in the LINEDEVCAPS data structure. For constants that are defined as bit flags, a range of low-order bits are reserved, where the high-order bits can be extension specific. It is recommended that extended values and bit arrays use bits from the highest value or high-order bit down. This leaves the option to move the border between the common portion and extension portion if there is a need to do so in the future. Extensions to data structures are assigned a variably sized field with size/offset being part of the fixed part. TAPI describes for each data structure what device-specific extensions are allowed.

In addition to recognizing a specific extension identifier, the application must negotiate the extension version number that the application and the service provider operate under. This is done in the second version negotiation phase of the lineGetDevCaps function.

An extension identifier is a globally unique identifier. There is no central registry for extension identifiers. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. The number is made up of parts such as a unique LAN address, time of day, and random number, to guarantee global uniqueness. Globally Unique Identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.


Extending Data Structures and Types

A range of values is reserved to accommodate future extensions to the Basic and Supplementary TAPI function set. For information about the amount by which a data structure can be extended, see Extensibility. For a list of the functions used for extending Telephony, see TAPI Quick Function Reference.


TAPI Levels of Service

TAPI telephony services are divided into Assisted Telephony services and the services provided by the full Telephony API. In general, the full Telephony API is used to implement powerful telephonic applications, and Assisted Telephony is used to add minimal but useful telephonic functionality to non-telephony applications. Telephony's services are divided into the groups shown in the following illustration:


Assisted Telephony Overview

A valuable feature of Win32 Telephony is the small set of functions called Assisted Telephony. Assisted Telephony is designed to make the establishment of voice calls and of media calls available to any Win32-based application, not just those dedicated to telephonic functionality. In other words, Assisted Telephony lets applications make telephone calls without needing to be aware of the details of the services of the full Telephony API. It extends telephony to word-processing applications, spreadsheets, databases, personal information managers, and other non-telephony applications.

For a list of TAPI 2.x Assisted Telephony functions of Basic Telephony, see TAPI Quick Function Reference. TAPI 3.x supports assisted telephony through the ITRequest interface.

The usefulness of Assisted Telephony can be illustrated by the following example. A spreadsheet application can incorporate functions that dial a telephone number for a speech call. As long as the application needs none of the detailed call control provided by the full Telephony API, Assisted Telephony is the easiest and most efficient way to give it telephonic functionality.

Assisted Telephony and the full Telephony API are used and implemented in different ways, so it is not advised to mix Assisted Telephony function calls and Telephony API function calls within a single application.

Using Assisted Telephony

Applications that use Assisted Telephony services only initiate call requests that are temporarily queued by TAPI. The request recipient application retrieves these requests and executes them on behalf of the Assisted Telephony application. The tapiRequestMakeCall function requests the establishment of a voice call. The requesting application does not control the call.

TAPI allows the user to establish different or the same request recipient applications for each of these services. An application becomes a request recipient by registering with lineRegisterRequestRecipient, in which TRUE is specified as the value for the parameter bEnable. (Specifying FALSE deregisters the application as a request recipient, which it should do when it has determined that its recipient duties are through for the current session.) The application selects the services it wants to handle in the dwRequestMode parameter of lineRegisterRequestRecipient. A possible value for a request is LINEREQUESTMODE_MAKECALL, to show that the application will handle tapiRequestMakeCall requests. If multiple applications register for the same services, a priority scheme is used to allow the user to select which application is preferred for handling requests. This priority scheme is identical to that used for call handoff and the routing of incoming calls based on a list of file names in HandoffPriorities in the registry.

Call Requests

Assisted Telephony provides telephony-enabled applications with an easy-to-use mechanism for making phone calls without requiring the developer to become fully literate in telephony.

The tapiRequestMakeCall function requests a voice call between the user and a remote party specified by its phone number. The request is made to TAPI, which passes it to an application that is registered as a recipient of such requests. This recipient is a call manager application.

After the application has made the request, the call is controlled entirely from the call manager application because Assisted Telephony applications cannot manage calls. Because the more complex aspects of telephony and all user-interface operations are handled by the call manager application, telephony-enabled applications need not be modified in any substantial way. In fact, applications that allow this operation to be invoked from their built-in script language may not need to be modified at all.

The tapiGetLocationInfo function returns to the application the country code and city (area) code that the user has set in the current location parameters in the Telephony Control Panel. The application can use this information to assist the user in forming proper canonical telephone numbers, such as by offering these as defaults when new numbers are entered in a phone book entry or database record.

Request Recipients

Two kinds of applications are needed to run Assisted Telephony. Assisted Telephony clients are applications that use Assisted Telephony by calling the functions that have the prefix "tapi." An example of such a client application would be a spreadsheet to which a Dial menu command or toolbar button is added.

Assisted Telephony servers are applications that can execute Telephony API functions that result from another application's call to a "tapi"-prefixed function. To make itself known as an Assisted Telephony server, such an application registers as one using the lineRegisterRequestRecipient function.

The functions of Assisted Telephony (which begin with the prefix "tapi") are known as request functions. Assisted Telephony applications that process these requests—Assisted Telephony servers—are called request recipients.

Processing Assisted Telephony Requests

The process with which requests are delivered and serviced is as follows:

  1. When TAPI receives an Assisted Telephony request, it checks for a request recipient, that is, an application currently registered to process that type of request. If there is a request recipient, the request is queued, and the highest-priority application that has registered for that request's service is sent a LINE_REQUEST message. The message notifies the request recipient that a new request has arrived, and it carries an indication of the request's mode.
  2. If TAPI cannot find a currently running application to process such a request, it tries to launch an application that has been registered as capable of doing so. This registration information is recorded in HandoffPriorities in the registry. TAPI tries to launch applications in the order in which they are listed in the HandoffPriorities section. (See the following step.)

    If no application is currently registered, TAPI examines the list of request-processing applications on the associated entry in HandoffPriorities. If the associated line is missing from the file, if there are no applications listed on it, or if none of the applications in the list can be launched, the request is rejected with the error TAPIERR_NOREQUESTRECIPIENT.

    When a request recipient is launched (whether or not it has been launched by TAPI) it is its duty to call lineRegisterRequestRecipient during the startup process and register itself as a request recipient.

  3. If one or more applications are listed in the entry, TAPI begins with the first listed application (highest priority), and attempts to launch it using the CreateProcess function. If the attempt to launch the application fails, TAPI attempts to launch the next application in the list. When any application launches successfully, TAPI simply queues the request and returns a success indication to the application even though the request hasn't yet been signaled to the request recipient.

    After the request recipient application is launched, it calls lineRegisterRequestRecipient, which causes a LINE_REQUEST message to be sent, signaling that the request is queued. If for some reason the launched application never registers, the request remains queued and remains in the queue indefinitely until an application registers for that type of request.

  4. If TAPI finds such a registered application already running or successfully launches one, it queues the request, sending a LINE_REQUEST message to the server application, and returns a success indication for the function call to the Assisted Telephony application. This success message states only that the request has been accepted and queued, not that it has been successfully executed.

When the server application is ready to process a request, it calls the lineGetRequest function. This lets it receive any information it needs, such as an address to dial. It then processes the request, using the TAPI functions (such as lineMakeCall and lineDrop) that would otherwise be used to place the call. Invoking lineGetRequest removes the request from TAPI, and the request parameters are copied in an application-allocated request buffer. The size and interpretation of the contents of the buffer depend on the request mode.

The server must ensure that it uses the correct parameters when executing requests. When doing so, these steps are followed:

  1. The request recipient first receives a LINE_REQUEST message informing it that requests can exist for it in the request queue. This tells the application to call lineGetRequest and keep calling it until the queue is drained (if the request is for making a new call), or to drop an existing call. This message does not contain the parameters for the request, except in the case of a request to drop an existing call.
  2. If the request is to make a new call, the Assisted Telephony server uses the lineGetRequest function to retrieve the full request, which includes the request's parameters. The server now has all the information it needs, such as the number to dial or the identification of the maker of the request. First, however, the server must allocate the memory needed to store this information.
  3. Finally, the server executes the request by invoking the appropriate TAPI function or set of functions.

If TAPI cannot launch an application capable of serving as a request recipient, the Assisted Telephony call fails and returns the error TAPIERR_NOREQUESTRECIPIENT.

Notes on Request Recipient Operations

The following information concerns systems on which Assisted Telephony requests are processed:

  • The default registry should list a call manager application in the priority list for tapiRequestMakeCall. It would be helpful, but not essential, for the call manager application to have a menu option that allows users to set it to the highest priority.
  • When an Assisted Telephony recipient application is launched automatically by TAPI and if it is the only TAPI application in the system, this action initializes TAPI. If the Assisted Telephony recipient application initializes and shuts down the line device before registering for Assisted Telephony requests, TAPI is shut down as well, and the Assisted Telephony request is lost. Assisted Telephony requests might also be lost when another TAPI application that is launched performs an initialize and shutdown.


Basic Telephony Services

Basic Telephony services are a minimal subset of the Win32 Telephony specification. Because all service providers must support the functions of Basic Telephony services, applications that use only these functions will work with any TAPI service provider. The functionality contained in Basic Telephony roughly corresponds to the features of POTS.

Many programmers will use only the services that Basic Telephony provides. Others, such as those writing code for PBX phone systems, will need the functions of Supplementary Telephony.

For a list of the functions of Basic Telephony, see TAPI Quick Function Reference.

Because control of phone devices is not assumed to be offered by all service providers, phone-device services are considered to be optional. That is, they are not a part of Basic Telephony. For a list of phone-device services, see Supplementary Telephony Services; for more information on phone devices, see TAPI Device Classes.


Supplementary Telephony Services

Supplementary Telephony services are the collection of all the services defined by the API other than those included in the Basic Telephony subset. It includes all so-called supplementary features found on modern PBXs, such as hold, transfer, conference, park, and so on. All supplementary features are considered optional; that is, the service provider decides which of these services it does or does not provide.

An application can query a line or phone device for the set of supplementary services it provides using functions such as lineGetDevCaps or lineGetAddressCaps. A single supplementary service may consist of multiple function calls and messages. The Telephony API, and not the service provider developer, defines the behavior of each of these supplementary features. A service provider should provide a Supplementary Telephony service only if it can implement the exact meaning as defined by the API. If not, the feature should be provided as an Extended Telephony service.

As mentioned in Basic Telephony services, phone-device services are considered optional. Therefore, all phone-device services are part of Supplementary Telephony. For a list of the functions of Supplementary Telephony, see TAPI Quick Function Reference.


Extended Telephony Services

The API contains a mechanism that allows service-provider vendors to extend the Telephony API using device-specific extensions. Extended Telephony services (or device-specific services) include all extensions to the API defined by a particular service provider. Because the API defines only the extension mechanism, the service provider must completely specify the definition of the Extended-Telephony service behavior.

TAPI 2 Extended Telephony

TAPI 2's extension mechanism allows service-provider vendors to define new values for some enumeration types and bit flags and to add members to most data structures. The interpretation of extensions is keyed off the service provider's extension identifier, an identifier for the specification of the set of extensions supported, which may cross several manufacturers. Special functions and messages such as lineDevSpecific and phoneDevSpecific are provided in the API to allow an application to directly communicate with a service provider. The service provider also defines the parameters for each function.

Vendors are not required to register in order to be assigned extension identifiers. Instead, a utility called EXTIDGEN (Extidgen.exe) is provided within the Microsoft Platform SDK that allows the local generation of extension identifiers. This unique identifier is composed of an Ethernet-adapter address, a random number, and the time of day. An identifier is assigned to a set of extensions (before distribution), not to each individual instance of an implementation of those extensions.


TAPI 3.1 (TAPI/COM) or TAPI 2.2 (TAPI/C)?

Microsoft's COM-based telephony API, currently version TAPI 3.0, is new with Windows 2000. TAPI/COM provides greatly enhanced development tools for the modern world of communication programming, where a "call" may be a video stream on an IP-based network and an actual phone set isn't involved at any point in the session. Generally speaking, application writers will find TAPI/COM gives them more capacity to implement flexible communications controls.

However, TAPI/C may be the right choice in some situations. If minor modifications are needed for a legacy application, conversion to the COM API may not be cost effective.


TAPI Version 2.2

TAPI Version 2.2 Start Page

Telephony Application Programming Interface

Version 2.2

Purpose

The Microsoft® Telephony Application Programming Interface (TAPI) version 2.2 (TAPI/C) allows you to implement communications applications ranging from basic modem control to call centers with multiple agents and switches.

Where Applicable

Possible applications include:

  • Basic voice calls on the Public Switched Telephone Network (PSTN)

  • Call center applications capable of tracking multiple agents

  • Modem control

  • PBX control

  • Interactive voice response (IVR) systems

  • Voice mail

  • Detailed phone device control

Developer Audience

TAPI/C is designed for use by C/C++ programmers. Previous development experience with telecommunications or other telephony applications is helpful but not necessary.

Run-time Requirements

TAPI version 2.2 enables development of communications applications for operating systems that support the Microsoft Win32® API, such as Microsoft Windows® 95, Microsoft Windows® Millennium Edition, or Microsoft Windows® 2000. For information on which operating systems support a particular function, see the Requirements section of the documentation for that function.

See Also

TAPI Version 3 General Description

TAPI Service Provider Overview

Overview

General information about TAPI's architecture and components.

Reference

Documentation of TAPI 2.2 functions, structures, messages, constants, and device classes.

Feedback

Make error reports and feature requests directly to Microsoft.


TAPI 2.2 Overview

The Microsoft® Telephony Application Programming Interface (TAPI) version 2.2 (TAPI/C) allows a developer to implement a range of communications applications. The following material presents overview information specific to using TAPI 2.2. Primary overview material is contained in The Microsoft Telephony Programming Model. Familiarity with this material is assumed.

Topics covered in this overview:

  • General Programming Considerations covers issues such as the versions, data structures, event notifications, and the handling of asynchronous functions.
  • Session Access covers some call session material specific to TAPI 2.2 (TAPI/C). See the general overview on Session Control for primary reference on call session operations and information.
  • Device Access covers capabilities specific to TAPI 2.2 (TAPI/C). See the general overview on Device Control for primary reference on device information and operations.
  • Media Access covers material on the media information and controls available to a TAPI 2.2 application. The media service providers give you access to more detailed controls, but only TAPI 3.0 (TAPI/COM) applications can use their capabilities. See About the Media Service Provider for additional information.
  • Call Center Control covers material on building Automatic Call Distribution (ACD) applications using TAPI 2.2. Please also see the TAPI 3.0 Call Center Controls Overview.
  • Phone Devices Overview covers the supplementary phone device controls supplied by TAPI 2.2 (TAPI/C).


General Programming Considerations

The following material covers topics relevant to multiple aspects of TAPI 2.2 (TAPI/C) applications programming, such as versioning.


TAPI/C Versioning

Over time, different versions of TAPI, applications, and service providers may be produced. These new versions can make new definitions, such as for new features, new members in data structures, and new bit fields. Version numbers are therefore necessary to indicate how to interpret various data structures.

To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, Microsoft Telephony provides a simple version negotiation mechanism for applications. There are two different versions that TAPI and the telephony service provider need to agree on for each line device. The first is the version negotiated with TAPI and the telephony service provider (TSP) Basic and Supplementary Telephony, referred to as the TAPI interface version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and data types used by TAPI's Basic and Supplementary features is defined by the TAPI version, while the extension version determines the format of data structures defined by the vendor-specific extensions.

The lineNegotiateAPIVersion function negotiates a TAPI version and lineNegotiateExtVersion negotiates the TSP extension version. A single TSP could be capable of handling more than one version, and an application must "fall back" to using an older version if using an older TSP. In lineNegotiateAPIVersion, the dwApiVersion parameter defaults to a value according to version, as follows.

TAPI version | dwApiVersion default value
1.3 | 0x00010003
1.4 | 0x00010004
2.0 | 0x00020000
2.1 | 0x00020001
2.2 | 0x00020002

However, TAPI makes this much easier as long as the TSP itself is using a newer version than the application. If the TSP is indeed newer, then TAPI is capable of translating "down" to the application's version. For example, TAPI 2.0 TSPs do not need to be specifically capable of dealing with TAPI version 1.4. If a TAPI 1.4 application is run, TAPI converts all TAPI 2.0 structures and messages into TAPI 1.4 equivalents, or as close as possible. If there is no close approximation in TAPI 1.4, then all TAPI 2.0-specific information will be lost.

The precise meaning of an extension version is provider-specific. To use a TSP that supports extensions, consult the provider's documentation.

There are a number of versions of TAPI. While most of these versions involved changes to the TAPI and Telephony Service Provider Interface (TSPI) documentation sets, there are other implications for each version, namely, architectural differences, operating system variations, redistributables, and TSP development issues.

TAPI version | Supported platforms
1.0 – 1.2 | Beta versions that should not be used any longer.
1.4 | Windows 95.
1.5 | Windows CE 1.0.
2.0 | Windows NT® 4.0 SP3.
2.1 | Part of Windows 98 and Windows NT 4.0 SP4. Available as a redistributable for Windows 95.
2.2 | Windows 2000.


TAPI Version 2.2

TAPI version 2.2 added specialized call center management functionality. Under previous versions of TAPI, call center software required careful mapping of lines and addresses to call center function. The new set of functions coordinates with TAPI 3.0 call center capabilities and makes the creation of ACD systems much easier.

For additional information, see TAPI 2.2 Call Center Control or About TAPI 3.0 Call Center Controls.


TAPI Version 2.1

TAPI version 2.1 made no changes to the previous TAPI 2.0 specification except for one major addition: client/server functionality. Now telephony hardware can be installed on a telephony server that can be accessed from any computer on a network. A new set of functions was added to allow administration DLLs to be written to control who has access to remote resources.

Note TAPI Client Management functionality is obsolete.

TAPI 2.1 allows Windows 95 and Windows 98 to support Win32-based TSPs. TSPs can be developed to run on both the Windows 95/98 and Windows NT/Windows 2000 platforms.

The TAPI 2.1 system binaries, when installed on Windows NT/Windows 2000, support exactly the same applications and TSPs as TAPI 2.0, with the addition of TAPI 2.1 support.

The TAPI 2.1 system binaries, when installed on Windows 95, support:

  • Win16 TAPI 1.3 and TAPI 1.4 applications
  • Win32 TAPI 1.3, TAPI 1.4, and TAPI 2.0 applications
  • Win16 TAPI 1.3 and TAPI 1.4 TSPs
  • Win32 TAPI 2.0 TSPs


TAPI Version 2.0

TAPI version 2.0 added a small number of enhancements to the basic TAPI 1.4 functionality. However, there were some major architectural changes that greatly improved its stability. Most of the changes were fundamental changes necessary to bring TAPI to Windows NT and take advantage of Windows NT/Windows 2000 features (full 32-bit support, services, and Unicode). However, these changes were internal to TAPI and had little effect on TAPI applications.

TAPI 1.3 and 1.4 applications (Win16-based applications by way of a thunking layer) work well on Windows NT 4.0 and Windows 2000. However, the effect on service-provider developers was significant. Service providers for Windows NT/Windows 2000 must be fully 32-bit Unicode DLLs that can run in the context of TAPISRV, not in the context of the TAPI application (as did all earlier Win16-based TSPs). TSPs designed for TAPI 1.4 do not work on Windows NT/Windows 2000.

TAPI 2.0 also added the important features of call center support and Quality of Service (QOS) support.

The TAPI system binaries that come with Windows NT 4.0 and Windows 2000 support TAPI versions 1.3 and 1.4 for both Win16- and Win32-based applications. However, only Win32-based applications have access to TAPI 2.0, and only 32-bit TAPI 2.0 (or later) TSPs are supported.


TAPI Version 1.5

TAPI version 1.5 was designed specifically for Windows® CE, Version 1.0. It is a subset rather than a superset of TAPI 1.4, is only available on Windows CE, and is documented in the Windows CE developer documentation.


TAPI Version 1.4

TAPI version 1.4 added a number of APIs, messages, constants, and structure elements to the 1.3 specification. TAPI 1.4 is a piece of Windows 95—it is always present and cannot be separated out for separate distribution. TAPI 1.4 supports only 16-bit TSPs. However, it does allow 32-bit applications to be developed without having to worry about Win16 limitations.

The TAPI and TSPI headers in the Platform SDK are used to develop both TAPI 1.4 and TAPI 2.0 applications. While there were not many changes to the structures between these two specifications, there were changes to the APIs (specifically, Unicode support) that make it very important to note that the headers compile differently, depending on the TAPI_CURRENT_VERSION constant. For an application to work correctly on Windows 95, it must define this variable. For example:

#define TAPI_CURRENT_VERSION 0x00010004
#include <tapi.h>

Note TAPI_CURRENT_VERSION should be defined for all TAPI applications. While it is not strictly necessary for TAPI 2.0 development, future changes could occur to require this.

TAPI 1.4 system binaries (as part of Windows 95) support both TAPI 1.3 and 1.4 applications and service providers. While applications can be either Win16- or Win32-based, TSPs can only be Win16 DLLs.


TAPI Version 1.3

TAPI version 1.3 (sometimes referred to as TAPI 1.03) was the first released version of the TAPI specification. The TAPI 1.3 system binaries (Tapi.dll and others) are found in the TAPI 1.0 SDK, which can be found only on the Microsoft® Developer Network (MSDN®) Level II subscription. The system binaries (found in the REDIST directory) are redistributable but are designed to run only on Microsoft Windows® 3.1 and Windows for Workgroups 3.11. They are not supported and will not work on any version of Microsoft Windows 95/98 or Microsoft Windows NT/Windows 2000.

The headers and libraries that are used to develop a TAPI 1.3 application are available only in the TAPI 1.0 SDK and support only Win16 development. In fact, the TAPI 1.3 libraries are the only Win16 libraries available and must be used for all Win16-based applications, regardless of the target platform or target version.

The TAPI 1.3 system binaries support only Win16, TAPI 1.3 TSPs, and applications.


TAPI Element By Version

In the past, if a TAPI programmer wanted to know whether a specific version of TAPI supported a particular TAPI function, a search of the Tapi.h file would likely reveal this information. While it is still possible to refer to the Tapi.h file, it is no longer necessary in determining which versions support which functions.

The following tables are a quick-reference alphabetical listing of TAPI functions and structures, together with the TAPI versions associated with each element.

TAPI functions | Use with TAPI version(s)
lineAccept | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineAddProvider |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineAddToConference | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineAgentSpecific |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineAnswer | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineBlindTransfer | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineCallbackFunc | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineClose | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineCompleteCall | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineCompleteTransfer | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineConfigDialog | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineConfigDialogEdit |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineConfigProvider |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineCreateAgent |  |  |  |  |  | 3.0
lineCreateAgentSession |  |  |  |  |  | 3.0
lineDeallocateCall | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineDevSpecific | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineDevSpecificFeature | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineDial | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineDrop | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineForward | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGatherDigits | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGenerateDigits | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGenerateTone | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetAddressCaps | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetAddressID | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetAddressStatus | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetAgentActivityList |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineGetAgentCaps |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineGetAgentGroupList |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineGetAgentInfo |  |  |  |  | 2.2 | 3.0
lineGetAgentSessionInfo |  |  |  |  | 2.2 | 3.0
lineGetAgentSessionList |  |  |  |  | 2.2 | 3.0
lineGetAgentStatus |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineGetAppPriority |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetCallInfo | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetCallStatus | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetConfRelatedCalls | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetCountry |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetDevCaps | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetDevConfig | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetGroupList |  |  |  |  | 2.2 | 3.0
lineGetIcon | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetID | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetLineDevStatus | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetMessage |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineGetNewCalls | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetNumRings | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetProviderList |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetProxyStatus |  |  |  |  | 2.2 | 3.0
lineGetQueueInfo |  |  |  |  | 2.2 | 3.0
lineGetQueueList |  |  |  |  | 2.2 | 3.0
lineGetRequest | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetStatusMessages | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineGetTranslateCaps | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineHandoff | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineHold | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineInitialize | 1.3 | 1.4 |  |  |  |
lineInitializeEx |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineMakeCall | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineMonitorDigits | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineMonitorMedia | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineMonitorTones | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineNegotiateAPIVersion | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineNegotiateExtVersion | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineOpen | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
linePark | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
linePickup | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
linePrepareAddToConference | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineProxyMessage |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineProxyResponse |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineRedirect | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineRegisterRequestRecipient | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineReleaseUserUserInfo |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineRemoveFromConference | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineRemoveProvider | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSecureCall | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSendUserUserInfo | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetAgentActivity |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineSetAgentGroup |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineSetAgentMeasurementPeriod |  |  |  |  | 2.2 | 3.0
lineSetAgentSessionState |  |  |  |  | 2.2 | 3.0
lineSetAgentState |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineSetAgentStateEx |  |  |  |  | 2.2 | 3.0
lineSetAppPriority |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetAppSpecific | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetCallData |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineSetCallParams | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetCallPrivilege | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetCallQualityOfService |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineSetCallTreatment |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineSetCurrentLocation | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetDevConfig | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetLineDevStatus |  |  | 2.0 | 2.1 | 2.2 | 3.0
lineSetMediaControl | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetMediaMode | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetNumRings | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetQueueMeasurementPeriod |  |  |  |  | 2.2 | 3.0
lineSetStatusMessages | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetTerminal | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetTollList | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetupConference | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSetupTransfer | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineShutdown | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineSwapHold | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineTranslateAddress | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineTranslateDialog |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineUncompleteCall | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineUnhold | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
lineUnpark | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneCallbackFunc | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneClose | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneConfigDialog | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneDevSpecific | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetButtonInfo | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetData | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetDevCaps | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetDisplay | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetGain | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetHookSwitch | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetIcon | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetID | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetLamp | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetMessage |  |  | 2.0 | 2.1 | 2.2 | 3.0
phoneGetRing | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetStatus | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetStatusMessages | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneGetVolume | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneInitialize | 1.3 | 1.4 |  |  |  |
phoneInitializeEx |  |  | 2.0 | 2.1 | 2.2 | 3.0
phoneNegotiateAPIVersion | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneNegotiateExtVersion | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneOpen | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetButtonInfo | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetData | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetDisplay | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetGain | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetHookSwitch | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetLamp | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetRing | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetStatusMessages | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneSetVolume | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
phoneShutdown | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
tapiGetLocationInfo | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
tapiRequestMakeCall | 1.3 | 1.4 | 2.0 | 2.1 | 2.2 | 3.0

TAPI structures | Use with TAPI version(s)
LINEADDRESSCAPS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEADDRESSSTATUS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEAGENTACTIVITYENTRY |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEAGENTACTIVITYLIST |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEAGENTCAPS |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEAGENTENTRY |  |  |  |  | 2.2 | 3.0
LINEAGENTGROUPENTRY |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEAGENTGROUPLIST |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEAGENTINFO |  |  |  |  | 2.2 | 3.0
LINEAGENTLIST |  |  |  |  | 2.2 | 3.0
LINEAGENTSESSIONENTRY |  |  |  |  | 2.2 | 3.0
LINEAGENTSESSIONINFO |  |  |  |  | 2.2 | 3.0
LINEAGENTSESSIONLIST |  |  |  |  | 2.2 | 3.0
LINEAGENTSTATUS |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEAPPINFO |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINECALLHUBTRACKINGINFO |  |  |  |  |  | 3.0
LINECALLINFO |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINECALLLIST |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINECALLPARAMS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINECALLSTATUS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINECALLTREATMENTENTRY |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINECARDENTRY |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINECOUNTRYENTRY |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINECOUNTRYLIST |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEDEVCAPS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEDEVSTATUS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEDIALPARAMS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEEXTENSIONID |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEFORWARD |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEFORWARDLIST |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEGENERATETONE |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEINITIALIZEEXPARAMS |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINELOCATIONENTRY |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEMEDIACONTROLCALLSTATE |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEMEDIACONTROLDIGIT |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEMEDIACONTROLMEDIA |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEMEDIACONTROLTONE |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEMESSAGE |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEMONITORTONE |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEPROVIDERENTRY |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEPROVIDERLIST |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEPROXYREQUEST |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINEPROXYREQUESTLIST |  |  |  |  | 2.2 | 3.0
LINEQUEUEENTRY |  |  |  |  | 2.2 | 3.0
LINEQUEUEINFO |  |  |  |  | 2.2 | 3.0
LINEQUEUELIST |  |  |  |  | 2.2 | 3.0
LINEREQMAKECALL |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINEREQMEDIACALL |  |  | 2.0 | 2.1 | 2.2 | 3.0
LINETERMCAPS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINETRANSLATECAPS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
LINETRANSLATEOUTPUT |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
PHONEBUTTONINFO |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
PHONECAPS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
PHONEEXTENSIONID |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
PHONEINITIALIZEEXPARAMS |  |  | 2.0 | 2.1 | 2.2 | 3.0
PHONEMESSAGE |  |  | 2.0 | 2.1 | 2.2 | 3.0
PHONESTATUS |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0
VARSTRING |  | 1.4 | 2.0 | 2.1 | 2.2 | 3.0


Version Negotiation

Over time, different versions may exist for TAPI, applications, and service providers for a line or phone. New versions may define new features, new fields to data structures, and so on. Version numbers therefore indicate how to interpret various data structures.

To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, TAPI provides a simple, two-step version negotiation mechanism for applications. Two different versions must be agreed on by the application, TAPI, and the service provider for each line device. The first is the version number for Basic and Supplementary Telephony and is referred to as the API version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and datatypes used by TAPI's basic and supplementary features is defined by the API version, while the extension version determines the format of the data structures defined by the vendor-specific extensions.

Version negotiation proceeds in two phases. In the first phase, the API version number is negotiated and the extension identifier associated with any vendor-specific extensions supported on the device is obtained. In the second phase, the extension version is negotiated. If the application does not use any API extensions, it skips the second phase and extensions are not activated by the service provider. If the application does want to use extensions, but the service provider's extensions (the extension identifier) are not recognized by the application, the application should skip the negotiation for extension version as well. Each vendor has its own set of legal (recognized) versions for each set of extension specifications it distributes.

The lineNegotiateAPIVersion function is used to negotiate the API version number to use. It also retrieves the extension identifier supported by the line device, returning zeros if no extensions are supported. With this function call, the application provides the API version range it is compatible with. TAPI in turn negotiates with the line's service provider to determine which API version range it supports. TAPI next selects a version number (typically, although not necessarily, the highest version number) in the overlapping version range that the application, the DLL, and the service provider have supplied. This number is returned to the application, along with the extension identifier that defines the extensions available from that line's service provider.

If the application wants to use the extensions defined by the returned extension identifier, it must first call lineNegotiateExtVersion to negotiate the extension version. In a similar negotiation phase, the application specifies the already agreed-upon API version and the extension version range it supports. TAPI passes this information to the service provider for the line. The service provider checks the API version and the extension version range against its own, and selects the appropriate extension version number, if one exists.

When the application later calls lineGetDevCaps, it returns a set of device capabilities for the line that correspond to the results of version negotiation. These include the line's device capabilities consistent with the API version and the line's device-specific capabilities consistent with the extension version. The application must specify both of these version numbers when it opens a line. At that point, the application, the DLL, and the service provider are committed to using the agreed-upon versions. If device-specific extensions are not to be used, the extension version should be specified as zero.

In an environment where multiple applications open the same line device, the first application to open the line device selects the versions for all future applications that want to use the line (service providers do not support multiple versions simultaneously.) Similarly, an application that opens multiple line devices may find it easier to operate all line devices under the same API version number.

Every function that takes a dwAPIVersion or similar parameter must set this parameter to either the highest API version supported by the application or the API version negotiated using the lineNegotiateAPIVersion or phoneNegotiateAPIVersion function on a particular device. Use the following table as a guide:

Function | Meaning
lineGetAddressCaps | Use version returned by lineNegotiateAPIVersion.
lineGetCountry | Use highest version supported by the application.
lineGetDevCaps | Use version returned by lineNegotiateAPIVersion.
lineGetProviderList | Use highest version supported by the application.
lineGetTranslateCaps | Use highest version supported by the application.
lineNegotiateAPIVersion | Use highest version supported by the application.
lineNegotiateExtVersion | Use version returned by lineNegotiateAPIVersion.
lineOpen | Use version returned by lineNegotiateAPIVersion.
lineTranslateAddress | Use highest version supported by the application.
lineTranslateDialog | Use highest version supported by the application.
phoneGetDevCaps | Use version returned by phoneNegotiateAPIVersion.
phoneNegotiateAPIVersion | Use highest version supported by the application.
phoneNegotiateExtVersion | Use version returned by phoneNegotiateAPIVersion.
phoneOpen | Use version returned by phoneNegotiateAPIVersion.

Important When negotiating an API version, always set the high and low version numbers to the range of versions that your application can support. For example, never use 0x00000000 for the low version or 0xFFFFFFFF for the high because these values require that your application support all versions of TAPI, both past and future.


Session Access

The primary reference for session operations and information is in the main overview for this SDK, under Session Control. This overview lists and defines the terminology involved, and provides jumps into the TAPI 2.2 and TAPI 3.0 reference pages for related programming elements.

The following material covers some information that is relevant only to TAPI 2.2 (TAPI/C).

  • Call Handles


Call Handles

As is mentioned in the Session Identifier overview, a call handle is the means by which a TAPI 2.2 application identifies a particular communications session. When an application initiates a session, TAPI returns a call handle for use in further operations or queries. When an application is notified of an incoming session, TAPI also passes in a call handle.

After a session has ended and the session state is idle, the call handle remains valid until the application deallocates the handle or the line is closed. The line might be closed by the application, or it may receive a LINE_CLOSE message. If a line is closed, all call handles to calls on the line instantly become invalid.

After a call reverts to the idle state, the application is still allowed to read the call's information structure and status. This enables applications to use operations such as lineGetCallInfo to retrieve call information for logging purposes.

When the application has no further use for the handle of an idle call, it should call lineDeallocateCall to free system-allocated memory related to the call. TAPI allocates memory for each call for each application that has a handle to the call. It is likely that service providers will allocate memory to hold call information as well. Deallocation of an application's call handle allows the library and the service provider to reclaim these memory resources. An application's handle for a call becomes void after a successful deallocation.

The application must itself free memory related to the call that it allocated for its own purposes.


Device Access

The primary reference for device operations and information is in the main overview for this SDK, under Device Control. This overview lists and defines the terminology involved, and provides jumps into the TAPI 2.2 and TAPI 3.0 reference pages for related programming elements.

The following material covers some information that is relevant only to TAPI 2.2 (TAPI/C).

  • Extended Line Functions
  • Passthrough Mode
  • Event Routing


Extended Line Functions

Extended line services (or device-specific line services) include all service-provider defined extensions to the API. The API defines a mechanism that enables service-provider vendors to extend TAPI using device-specific extensions. The API only defines the extension mechanism, and by doing so provides access to device-specific extensions, but the API does not define their behavior. Behavior is completely defined by the service provider.

TAPI consists of scalar and bit-flag constant definitions, data structures, functions, and messages. Procedures are defined that enable a vendor to extend most of these as follows.

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. As most data constants are DWORDs, typically the range 0x00000000 through 0x7FFFFFFF is reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF are available for vendor-specific extensions. The assumption is that a vendor would define values that are natural extensions of the data types defined by the API.

For extensible bit-flag data constants, a service-provider vendor can define new values for specified bits. As most bit-flag constants are DWORDs, typically a specific number of the lower bits are reserved for common extensions while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up; vendor-specific extensions should be assigned from bit 31 down. This provides maximum flexibility in assigning bit positions to common extensions versus vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by the API.

Extensible data structures have a variably sized field that is reserved for device-specific use. Being variably sized, the service provider decides the amount of information and the interpretation. A vendor that defines a device-specific field is expected to make these natural extensions of the original data structure defined by the API.

Two functions, lineDevSpecific and lineDevSpecificFeature, and two related messages, LINE_DEVSPECIFIC and LINE_DEVSPECIFICFEATURE, provide a vendor-specific extension mechanism. The lineDevSpecific function and associated LINE_DEVSPECIFIC message enable an application to access device-specific line, address, or call features that are unavailable with the Basic or Supplementary Telephony services. The parameter profile of the lineDevSpecific function is generic in that little interpretation of the parameters is made by the API. The interpretation of the parameters is defined by the service provider and must be understood by an application that uses them. The parameters are simply passed through TAPI from the application to the service provider. An application that relies on device-specific extensions will not generally work with other service providers; however, applications written to the Basic and Supplementary Telephony services will work with the extended service provider.

For convenience, a more specialized escape function is also provided. It is similar to lineDevSpecific, but places interpretation on some of the parameters. This more specialized function is lineDevSpecificFeature, a device-specific escape function to allow sending switch features to the switch. The message LINE_DEVSPECIFICFEATURE is the device-specific message sent to the application as an indication of features sent to the switch. This function and its associated message allow an application to emulate button presses at the line's feature phone. As feature phones and the meanings of their buttons are vendor-specific, feature invocation using lineDevSpecificFeature is also vendor specific.

As mentioned earlier, there is no central registry for manufacturer identifiers. Instead, a unique identifier generator (EXTIDGEN) is made available.


Passthrough Mode

When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. Applications can use this mode for temporary direct control over asynchronous modems, accessed through the Win32 Communication functions, for the purpose of configuring or using special features not otherwise supported by the service provider, such as facsimile (Class 1, 2, and so on). This bearer mode is supported by the Universal Modem Driver (UNIMODEM) service provider.

Service providers that support LINEBEARERMODE_PASSTHROUGH indicate it in the dwBearerModes member of the LINEDEVCAPS structure. When LINEBEARERMODE_PASSTHROUGH is indicated, the Unimodem service provider will also include in the DevSpecific area of the LINEDEVCAPS structure the registry key used to access information about the modem associated with the line device, in the following format:

struct {
    DWORD dwContents;   // Set to 1 (indicates containing key)
    DWORD dwKeyOffset;  // Offset to key from start of this
                        // structure (not from start of
                        // LINEDEVCAPS structure). 8 in
                        // our case.
    BYTE rgby[...];     // place containing null-terminated
                        // registry key.
}

For example:

    00000001 00000008 74737953 435c6d65  ........System\C
    65727275 6f43746e 6f72746e 7465536c  urrentControlSet
    7265535c 65636976 6c435c73 5c737361  urrentControlSet
    65646f4d 30305c6d xx003030 xxxxxxxx  Modem\0000.

This registry key could then be opened using this function:

RegOpenKey(HKEY_LOCAL_MACHINE, pszDevSpecificRegKey, &phkResult)

Passthrough mode is invoked most often using the lineMakeCall function, by setting the LINEBEARERMODE_PASSTHROUGH bit in the dwBearerMode member of the LINECALLPARAMS structure pointed to by the lpCallParams parameter. When this is done, the service provider will open the serial port to the modem and immediately place the call into LINECALLSTATE_CONNECTED. The application can then use the lineGetID function with the device class "comm/datamodem" to obtain an open Win32 file handle to read from and write to the comm port.

Passthrough mode can be invoked in response to an incoming call as well. Generally, applications will invoke passthrough mode while the call is in LINECALLSTATE_OFFERING, before the call has been answered. Instead of calling lineAnswer, the application calls lineSetCallParams, passing LINEBEARERMODE_PASSTHROUGH as the dwBearerMode parameter. When this is done, as with lineMakeCall, the call will immediately be placed into LINECALLSTATE_CONNECTED by the service provider, and the application can obtain a handle to the open port using lineGetID. The lineSetCallParams function can be called when the call is in LINECALLSTATE_OFFERING, LINECALLSTATE_ACCEPTED, or LINECALLSTATE_CONNECTED.

Passthrough mode is normally terminated by calling lineDrop on the call handle obtained from lineMakeCall or the first LINE_CALLSTATE message (if the call was an incoming call). The service provider will close the port, and restore the modem to its default state. The application must call CloseHandle on the handle it received from lineGetID.

Passthrough mode can also be terminated by calling lineSetCallParams with the dwBearerMode parameter set to LINEBEARERMODE_VOICE. The media type (mode) set by lineSetMediaMode is presumed to be in effect. If LINEMEDIAMODE_DATAMODEM is active, the service provider will take over the call as though it was a data modem call already in progress; if lineDrop is subsequently called, the service provider will issue the appropriate modem commands or interface state changes to drop a data call.


Event Routing

With the lineSetTerminal function, the application can control or suppress the routing of specified low-level events (exchanged between the switch and the station) to a device. With lineSetTerminal, the application specifies the terminal device to which these events (such as line, address, or call media-stream events) are routed.

The routing of the different classes of events can be individually controlled, allowing separate terminals to be specified for each event class. Event classes include lamps, buttons, display, ringer, hookswitch, and media stream.

For example, the media stream of a call (voice, for example) can be sent to any transducer device if the service provider and the hardware is capable of doing so. In general, a transducer means the same as what is referred to as a hookswitch device in TAPI, something that has a microphone and a speaker. Ring events from the switch to the phone can be mapped into a visual alert on the computer's screen or they can be routed to a phone device. Lamp events and display events can be ignored or routed to a phone device (which appears to behave as a normal phone set). Finally, button presses at a phone device may or may not be passed to the line. In any case, this routing of low-level signals from the line does not affect the operation of the line portion of TAPI, which always maps low-level events to their functional equivalent. To determine the terminals a line device has available (and their capabilities), consult the line device's capabilities with lineGetDevCaps.

Assume initially that the application has suppressed the routing of all events (with lineSetTerminal), and the user selects a headset as the current I/O device. An incoming call sends a LINE_CALLSTATE message, and a LINE_LINEDEVSTATE message with the ringing indication. Because routing of all events is suppressed, ring events are not routed to the phone, so ringing is suppressed. Instead, the application notifies the user with a pop-up dialog box and a system beep in the headset.

The user decides to answer the call. Because the user's current I/O device is the headset, the telephony application invokes lineSetTerminal on the incoming call to route the call's media to the headset and answer the call. The application may also invoke lineSetTerminal to route lamp and display information events to the phone set so that it will behave as usual.

As a second example, assume that an incoming call is alerting at the user's computer. Instead of selecting the answer option with the mouse, the user decides to just pick up the phone's handset to answer the call. The offhook status at the phone sends a message to the application. The application can interpret this status as a request by the user to select the phone handset to conduct the conversation. The application then invokes lineSetTerminal to route the voice data on the call to the phone set.


Special Hardware

Some of the more advanced capabilities of TAPI require that an application be able, for example, to retrieve data from telephones. Most telephones cannot be connected directly to computers to control speech calls and thus are currently incapable of supporting telephony functions beyond the passive role they play in POTS. In the future, users will install and configure telephone sets like other peripheral devices. The sets will be accompanied by cards that will control the flow of information between the computer and the telephone. Client/server configurations will also be possible that allow users to take advantage of telephonic services by connecting over a LAN to a server that has such a board and associated software installed.


Media Access

Media capabilities are quite different under TAPI 2.2 (TAPI/C) as opposed to TAPI 3.0 (COM), largely because the COM API has access to media service providers (MSPs). Please see About The Media Service Provider (MSP) for additional information on MSPs and Media Control for a general review of media stream operations and information.

The two most important concepts for an application are the media type (or mode) and the stream. The type is the form in which data is transmitted. For a list of types defined by TAPI, see LINEMEDIAMODE_ Constants. The media stream is the actual stream of information that travels on the line. An MSP can provide direct access to the stream. TAPI 2.2 applications have some access, but primarily reference other APIs to implement such controls.

These APIs include the Waveform API, the Comm API, and the Media Control Interface (MCI). The Waveform API is used for multimedia programming, the Comm API is the set of communications functions provided by the Microsoft Platform SDK, and the MCI provides a high-level generalized interface for controlling media devices.

For example, for line devices, an application can use TAPI 2.2 to establish a connection to another station. Once the connection is established, the application can then use the Waveform API (or the MCI Waveaudio API) on the associated device to play back (send) and record (receive) audio data over the connection. Similarly, if the connection's media stream is from a modem, an application would use the modem configuration extensions of the Comm API to control the media stream.

To provide TAPI 2.2 with media-stream access to either a phone or a call on a line device, the service provider must implement both the Telephony SPI and the appropriate media stream SPI or DDI (device-driver interface). The service provider can support lines and phones simultaneously.

Because these device classes and media stream operations function independently of one another, coordination of their usage must occur at the application level. Multiple applications that share calls and media streams in nontrivial ways will likely need to coordinate their activities at the application level to prevent conflicting usage of TAPI and the media stream API in use.

TAPI reports changes in the type of media stream (voice, fax, data modem, and so on) to participating applications. This process is sometimes referred to as call classification. The mechanism used to determine the type of media stream is specific to the service provider. For example, a service provider may filter the media stream for energy or tones that characterize the media type, or it may use distinctive ringing, information exchanged in messages over the network, or knowledge about the caller or called ID to make this determination.

  • Call Monitoring
  • Media Control
  • Digit Gathering
  • Generating Inband Digits and Tones


Call Monitoring

Call monitoring includes media, digit, and tone monitoring, as described in the following topics.

  • Media Monitoring
  • Digit Monitoring
  • Tone Monitoring


Media Monitoring

When a call is in the connected state, information can be transported over the call. A call's media type provides an indication of the type of information (for example, its datatype, or higher-level protocol) of this media stream.

TAPI allows applications to be provided with a notification about changes in a call's media type. The notification provides an indication of the call's new media type. The service provider decides how it wants to make this determination. For example, the service provider could use signal processing of the media stream to determine the media type, or it could rely on distinctive ringing patterns assigned to different media streams, or on information elements passed in an out-of-band signaling protocol. Independent of how the media type determination is achieved, the application is simply informed about media type changes on an existing call.

See LINEMEDIAMODE_ Constants for a list of currently defined TAPI media types or modes. Service providers may implement provider-specific media types for highly specialized devices. Information on these will be found in device documentation.

The media types defined by TAPI include.

  • Unknown The media type of the call is not currently known—the call is unclassified.
  • Interactive voice Voice energy was detected on the call, and the call is handled as an interactive voice call with a person at the application's end.
  • Automated voice Voice energy was detected on the call, and the call is handled as a voice call but with no person at the application's end, such as with an answering machine application.
  • Data modem A modem session on the call. Current modem protocols require the called station to initiate the handshake. For an incoming data modem call, the application can typically make no positive detection. How the service provider makes this determination is its choice. For example, a period of silence just after answering an incoming call can be used as a heuristic to decide that this might be a data modem call.
  • G3 fax A group 3 fax session on the call.
  • G4 fax A group 4 fax session on the call.
  • TDD The call's media stream uses the Telephony Devices for the Deaf protocol.
  • Digital data A digital data stream of unspecified format.
  • Teletex, Videotex, Telex, Mixed These correspond to the telematic services of the same names.
  • ADSI An Analog Display Services Interface session on the call. ADSI enhances voice calls with alphanumeric information downloaded to the phone and the use of soft buttons on the phone.

An application can enable or disable media monitoring on a specified call with lineMonitorMedia. The application specifies which media types it is interested in monitoring, and when media monitoring is enabled, the detection of a media type change causes the application to be notified with the LINE_MONITORMEDIA message. This message provides the call handle on which the media type change was detected as well as the new media type.

There is a distinction between the media type of a call as reported by lineGetCallInfo and the media type event reports by LINE_MONITORMEDIA messages. A call's media type is determined exclusively by owner applications of the call and is not automatically changed by media monitoring events. The one exception is the initial media type determination that can be performed by the TAPI dynamic-link library to select the first owner of a call. One could argue that in this case, the library is the owner of the call.

Default media type monitoring is performed for the media types for which the line device has been opened. This allows an incoming call's media type to be determined before the call is handed to an application based on what the application demands. The scope of the media monitoring of a call is bound by the lifetime of the call. Media monitoring on a call ends as soon the call disconnects or goes idle.

An application can obtain device identifiers for various device classes associated with an opened line by calling lineGetID. This function takes a line handle, address, or call handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open line device, address, or call. If the device class is "tapi/line," then the device identifier of the line device is returned. If the device class is "mci/wave," then the device identifier of an mci waveaudio device is returned (if supported), which allows activities such as the recording or playback of audio over the call on the line.

The application can use the returned device identifier with the corresponding media API to query the device's capabilities and subsequently open the media device. For example, if your application needs to use the line as a waveform device, it must first call waveInGetDevCaps and/or waveOutGetDevCaps to determine the waveform capabilities of the device. The typical waveform data format supported by telephony in North America is 8-bit m-law at 8000 samples per second, although the wave device driver can convert this sample rate and companding to other more common multimedia audio formats.

To subsequently open a line device for audio playback using the waveform API, an application calls waveOutOpen. The implementation of waveOutOpen is device specific, and there are a variety of options for implementing this function.


Digit Monitoring

Digit monitoring monitors the call for digits. TAPI allows digits to be signaled according to two methods (digit modes):

  • Pulse Digits are signaled as pulse or rotary sequences. For detection, these pulses manifest themselves as nothing more than sequences of audible clicks. Valid pulse digits are '0' through '9'.
  • DTMF Digits are signaled as DTMF (Dual Tone Multiple Frequency) tones. Valid DTMF digits are '0' through '9', 'A'. 'B', 'C', 'D', '*', and '#'. Both the beginning and the down edge of DTMF digits can be monitored.

An application can enable or disable digit monitoring on a specified call with lineMonitorDigits. When digit monitoring is enabled, detected digits cause the application to be notified with the LINE_MONITORDIGITS message. This message provides the call handle on which the digit was detected as well as the digit value and the digit mode. The scope of digit monitoring is bound by the lifetime of the call. Digit monitoring on a call ends as soon as the call disconnects or goes idle.


Tone Monitoring

Tone monitoring monitors the media stream of a call for specified tones. A tone is described by its component frequencies and cadence. An implementation of the API may allow several different tones to be monitored simultaneously. An application can tag each tone to be able to distinguish the different tones for which it requests detection.

An application can enable or disable tone monitoring on a specified call with lineMonitorTones. With this function, the application indicates which tones to detect on a specified call. When tone monitoring is enabled, detected digits cause the application to be notified with the LINE_MONITORTONE message. This message provides the call handle on which the tone was detected as well as the application's tag for the tone.

The scope of tone monitoring is bound by the lifetime of the call. Tone monitoring on a call ends as soon the call disconnects or goes idle.

Note The monitoring of tones, digits, or media types often requires the use of resources of which the service provider can only have a finite amount. A request for monitoring can be rejected if resources are not available. For the same reason, an application should disable any unnecessary monitoring.


Media Control

An application can request the execution of a limited set of media-control operations on the call's media stream triggered by telephony events. Although an application is encouraged to use the media API specifically defined for the media type or TAPI 3.0's media controls, TAPI 2.2 media control can yield a significant performance improvement for client/server implementations. The lineSetMediaControl function is used to set up a call's media stream for media control by allowing an application to specify a list of tuples specifying a telephony event and the associated media-control action. The following are telephony events that can trigger media-control activities.

  • Detection of a digit: The application provides a list of specific digits and the media-control action that each of them triggers.
  • Detection of a media type: The application provides a list of media types and the media-control actions that a transition into the media type triggers.
  • Detection of a specified tone: The application specifies a list of tones and the media-control action that each tone detection triggers.
  • Detection of a call state: The application specifies a list of call states and the media-control action that each transition to the call state triggers.

The media-control actions listed below are defined generically for the different media types. Not all media streams can provide meaningful interpretations of the media-control actions. The operations should map well to audio streams:

  • Start starts the media stream.
  • Reset resets the media stream.
  • Pause stops or pauses the media stream.
  • Resume starts or resumes the media stream.
  • Rate up increases the rate (speed) of the media stream by an implementation-defined amount.
  • Rate down decreases the rate of the media stream by an implementation-defined amount.
  • Rate normal returns the rate to normal.
  • Volume up increases the volume (amplitude) of the media stream.
  • Volume down decreases the volume of the media stream.
  • Volume normal returns the volume to normal.

The scope of media control is bound by the lifetime of the call. Media control on a call ends as soon the call disconnects or goes idle. Only a single media-control request can be outstanding on a call across all applications.


Digit Gathering

Besides enabling digit monitoring and being notified of digits one at a time, an application can also request that multiple digits be collected in a buffer. Only when the buffer is full or when some other termination condition is met is the application notified. Digit gathering is useful for functions such as credit card number collection. It is performed when an application calls lineGatherDigits, specifying a buffer to fill with digits. Digit gathering terminates when one of the following conditions is true:

  • The requested number of digits has been collected.
  • One of multiple termination digits is detected. The termination digits are specified to lineGatherDigits, and the termination digit is placed in the buffer as well.
  • One of two timeouts expires. The timeouts are a first digit timeout, specifying the maximum duration before the first digit must be collected, and an inter-digit timeout, specifying the maximum duration between successive digits.
  • Digit gathering is canceled explicitly by lineGatherDigits again with either another set of parameters to start a new gathering request or by using a NULL digit buffer parameter to cancel.

When digit gathering terminates for any reason, a LINE_GATHERDIGITS message is sent to the application that requested the digit gathering. Only a single digit gathering request can be outstanding on a call at any given time across all applications that are owners of the call.

Digit gathering and digit monitoring can be enabled on the same call at the same time. In that case, the application will receive a LINE_MONITORDIGITS message for each detected digit and a separate LINE_GATHERDIGITS message when the buffer is sent back.


Generating Inband Digits and Tones

After a call is in the connected state, information can be transmitted over it. Two functions are provided that allow end-to-end inband signaling between the application and remote station equipment such as an answering machine. One function is lineGenerateDigits, which generates inband digits on a call, signaling them over the voice channel. Digits can be signaled as either rotary/pulse sequences or as DTMF tones. The other function is lineGenerateTone, which enables the application to generate one of a variety of multifrequency tones inband (over the media stream). This generates telephony tones, such as ringback, beep, and busy, as well as arbitrary multifrequency, multicadenced tones.

Only one digit or tone generation can be in progress on a call at any one time. When digit or tone generation completes, a LINE_GENERATE message is sent to the application that requested the generation. In the case where multiple digits are generated, only a single message is sent back after all digits have been generated. Calling lineGenerateDigits or lineGenerateTone while digit or tone generation is in progress will abort the generation currently in progress and send the LINE_GENERATE message to the application whose generation was aborted with a cancel indication.


Call Center Control

Basic TAPI 2.2 can be used to manage call centers and other elements of Telephony network infrastructure (such as IVR and voice mail servers) through third-party call control.

With the release of TAPI 3.0, this API becomes the preferred means of writing ACD Agent applications. Please see the TAPI 3.0 Call Center Controls Overview section for information on using these interfaces and methods. However, TAPI 2.2 remains useable for full ACD application suites if desired.

To create an ACD Proxies that will run on a server, functions have been added to TAPI 2.2 to provide additional assistance to application developers.

The following topics describe the TAPI 2.2 features that you can use to implement call center controls:

  • Modeling of a Call Center
  • Stations
  • Predictive Dialing
  • Call Queues and Route Points
  • ACD Agent Monitoring and Control
  • Station Status Control
  • Station Status Control
  • Call State Timer
  • Media Event Timers


Modeling of a Call Center

Service providers can expose each resource on the PBX as a line device and possibly an associated phone device. Terminals that support multiple call appearances would do so through multiple addresses, just as in first-party call control. In fact, the third-party view of a device is identical to the first-party view; applications on the server can see and control all of the first-party devices, whereas an individual client PC connected to the server can only see those devices that are made visible to it through access controls administered by tapisrv.exe on the server. Resources other than terminals can also be modeled as line devices. For example, an ACD queue or route point would be modeled as a line device that could have many active calls; an IVR server, voice mail server, or set of predictive dialing ports could also be modeled as a line device that supports multiple calls.

Within this model, the status of the addressed device and calls associated with it can be monitored though existing TAPI messages such as LINE_LINEDEVSTATE, LINE_ADDRESSSTATE, LINE_CALLSTATE, and LINE_CALLINFO, and details obtained through functions such as lineGetLineDevStatus, lineGetAddressStatus, lineGetCallStatus, and lineGetCallInfo. Whenever a TAPI object is operated upon through a third-party application running on the server, the result is identical to what would have occurred if the same object had been similarly operated on by a first-party application running on a client PC associated with that device. Status indications sent by the server service provider controlling the switching fabric (or switch) are delivered both to applications running on the server and to those running on associated, authorized clients.


Stations

Station sets being monitored through a third-party link are modeled as a line device and possibly an associated phone device. The line device can have multiple addresses, if the modeled terminal supports more than one directory number (DN). Multiple call appearances on the same DN can be modeled as a single address that supports multiple calls.

Calls between two stations on the switch have two call handles, one giving the call view from the first station (on its line device), and the other giving the call view from the second station (on its line device). For example, a third-party lineMakeCall placed by an application on the server would be directed to the line device associated with the station from which the call is to be dialed; a call handle would be created on that line, on the address specified in LINECALLPARAMS (thereby giving control over which DN is used on a phone that supports multiple DNs). When the call is offered to the destination address, a new call handle showing a call in offering state is created; applications would know that it was another view of the same call by the dwCallID member in LINECALLINFO being equal for both calls. Both calls would go idle when the call was dropped; a call could be dropped from the third-party application by doing a lineDrop on either of the call handles.


Predictive Dialing

Predictive dialing is an application that typically runs on a call center telephony server. It uses a list of phone numbers, often obtained from a database, to attempt outgoing calls; when a call is completed, the call is automatically assigned to an agent for handling. The application can make use of a predictive dialing port on a switch, which is a device that can make outgoing calls and has special abilities (through DSP, and so on) to detect call progress tones and other audible indications of call state. When a call is made on a predictive dialing port, typically it is automatically transferred to another device on the switch when the call reaches a particular state or upon detection of a particular media type; this target device can be a queue for agents handling outgoing calls.

Applications identify a device as having predictive dialing capability by the LINEADDRCAPFLAGS_PREDICTIVEDIALER bit in the dwAddrCapFlags member in LINEADDRESSCAPS. The dwPredictiveAutoTransferStates member in LINEADDRESSCAPS indicates the states upon which the predictive dialing port can be commanded to automatically transfer a call; if this member is zero, it indicates that automatic transfer is not available, and that it is the responsibility of the application to transfer calls explicitly upon detecting the appropriate call state (or media type or other criteria). Preferably, switch manufacturers will make available both automatic and manual transfer, and allow applications to select the preferred mechanism, but service providers would have to model the behavior of legacy equipment. A single predictive dialing port (line device/address) can support making several outgoing calls simultaneously, as indicated by the dwMaxNumActiveCalls member in LINEADDRESSCAPS. Predictive dialing capability can also be made available on any device, using a shared pool of predictive dialing signal processors, which are bridged onto the line being dialed upon request.

When the lineMakeCall function is used on a line capable of predictive dialing (a port with the LINEADDRCAPFLAGS_PREDICTIVEDIALER set) and predictive dialing is requested using LINECALLPARAMFLAGS_PREDICTIVEDIAL, then the call is made in a predictive fashion with enhanced audible call progress detection. Additional fields and constants are defined in the LINECALLPARAMS structure passed in to lineMakeCall to control the behavior of the predictive dialing port. The dwPredictiveAutoTransferStates member indicates the line call states that, upon entry of the call into any of them, the predictive dialing port should automatically transfer the call to the designated target (the bits must be a proper subset of the supported auto-transfer states indicated in LINEADDRESSCAPS); the application can leave the field set to 0 if it desires to monitor call states itself and use lineBlindTransfer to transfer the call when it reaches the desired condition. The application must specify the desired address to which the call should be automatically transferred in the variable field defined by the dwTargetAddressSize and dwTargetAddressOffset members in LINECALLPARAMS.

Applications can also set a timeout for outgoing calls so that the service provider automatically transitions them to a disconnected state if they are not answered. This is controlled using the dwNoAnswerTimeout member in LINECALLPARAMS.


Call Queues and Route Points

A call queue or route point is a special address within the switch where calls are temporarily held pending action. This characteristic is represented by the bits LINEADDRCAPFLAGS_QUEUE and LINEADDRCAPFLAGS_ROUTEPOINT in the dwAddrCapFlags member in LINEADDRESSCAPS. All calls appearing on such an address are awaiting action by the application, and there can be default actions that take place (for example, transfer to an agent or trunk) if the application takes no action within a defined period of time. The application must be configured by the system administrator so that it knows what actions it should take regarding calls appearing on each queue or route point address, and the amount of time available to decide on the action to take.

Applications can determine the number of calls pending in a queue or route point using lineGetAddressStatus. The lineGetCallInfo function can be used to obtain information such as calling ID, called ID, incoming or outgoing origin, and so on, and used by the application to make decisions on call handling; calls can be redirected, blind-transferred, dropped, and so on, or just allowed to automatically pass out of the queue to a destination. A call goes to LINECALLSTATE_DISCONNECTED if it is abandoned. Calls go idle when they leave the queue; lineGetCallInfo can be used to read the redirection identifier to determine where they were transferred.

Some switches allow calls in a queue or on hold to receive particular treatment such as silence, ringback, busy signal, music, or listening to a recorded announcement. The lineSetCallTreatment function allows the application to control the treatment. The structure delimited by the dwCallTreatmentListSize and dwCallTreatmentListOffset members in LINEADDRESSCAPS allows applications to determine the supported treatments. The dwCallTreatment member in LINECALLINFO indicates the current treatment, and a LINE_CALLINFO message with LINECALLINFOSTATE_TREATMENT indicates when this changes. The LINECALLFEATURE_SETTREATMENT bit in the dwCallFeatures member in LINECALLSTATUS indicates when the application is permitted to change the treatment. The LINECALLTREATMENT_ set of constants defines a limited set of predefined call treatments; service providers can define many more.


ACD Agent Monitoring and Control

Monitoring and control of ACD agent status on stations is supported through these functions: lineGetAgentCaps, lineGetAgentStatus, lineGetAgentGroupList, lineGetAgentActivityList, lineSetAgentGroup, lineSetAgentState, and lineSetAgentActivity.

The LINE_AGENTSTATUS message is used to indicate when agent information has changed.

These controls are associated with an address instead of a line because many ACD systems are implemented with different ACD queues associated with buttons on the phone terminal (and separate call appearances). Also, ACD agent phones can often have separate call appearances for personal calls.

Architecturally, ACD functionality should be implemented in a server-based application. The client functions mentioned above, rather than mapping to the telephony service provider, are conveyed to a server application that has registered (using an option of lineOpen) as a handler for such functions. The LINE_PROXYREQUEST message is used to signal to the handler application when a request has been made; it calls the lineProxyResponse function to return results and data. Handler applications can also call lineProxyMessage to generate LINE_AGENTSTATUS messages when required. In the case of a legacy PBX or stand-alone ACD that implements ACD functionality itself, the telephony service provider for the switch must include a proxy server application that accepts the requests and routes them (possibly using lineDevSpecific functions or a private interface) to the service provider, which routes them to the switch.


Station Status Control

There are three major station status functions that need control: Message Waiting lights, Forwarding, and Do Not Disturb. Forwarding and Do Not Disturb are controllable through the existing lineForward function (which is address-specific), and queried using lineGetAddressStatus. The LINEDEVSTATUSFLAGS_MSGWAIT bit in the dwDevStatusFlags member of LINEDEVSTATUS indicates the status of the message waiting light on the device, and a LINEDEVSTATE_MSGWAITON or LINEDEVSTATE_MSGWAITOFF message is sent to indicate when the state changes. The lineSetLineDevStatus function allows the message waiting light to be controlled without having to implement a TAPI phone device just for that purpose. The LINEFEATURE_SETDEVSTATUS bit (in the dwLineFeatures member of LINEDEVCAPS and LINEDEVSTATUS) indicates when it can be called, and the dwSettableDevStatus member of LINEDEVCAPS allows the application to detect which device status settings can be controlled from the application. In addition to allowing the message waiting feature to be controlled, it also allows the device's Connected, Inservice, and Locked status to be set, to the extent that these are supported by the switch or other hardware. Calls to this function result in appropriate LINE_LINEDEVSTATE messages being sent to reflect the new status.


Call State Timer

Currently, all timing of calls is left up to applications. This can be burdensome if the application is monitoring a large number of calls, and if multiple applications are present, possibly on multiple servers, it can be necessary for them to all maintain timers on the same calls. It therefore makes more sense for call state timing to be handled by the server.

The tStateEntryTime member in LINECALLSTATUS allows timing of calls in states to be reported. The member (of type SYSTIME) indicates the time at which the current state was entered.


Media Event Timers

Many applications depend on the timing relationship between media events (for example, DTMF digits received) in order to determine the nature of a requested operation. For example, in a voice mail application, two consecutive DTMF "1" digits may mean "back up two segments" or "replay from beginning of message", depending on how much time elapsed between the two digits. In a client/server environment, if the DTMF detection is being performed on a separate processor from the one on which the application is running, latency in the local area network makes it very likely that the timing relationship between media events will be skewed, with the result that these timing-based differences could be lost or become unreliable.

To resolve this issue, several TAPI messages can be timestamped. Because it is the relative timing between these events that is important, the "clock time" of the event is not important, and sub-second timing is involved, these timestamps use the millisecond-resolution "time since Windows started" returned by the GetTickCount function. Applications must be aware that this is the tick count on the server (or machine where the service provider directly managing the hardware is running), and is not necessarily the same machine on which the application is executing; thus, the timestamps in these TAPI messages can only be compared to each other, and not to the value returned by GetTickCount on the processor on which the application is running.

The TAPI messages that can be timestamped are: LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, and LINE_MONITORTONE. The tick count is inserted into dwParam3 of these messages. If timestamping is not supported by the service provider (which is indicated by the service provider setting dwParam3 in these messages to 0), then TAPI itself will insert the tick count into dwParam3 of all of these messages (it can be skewed somewhat, but less than if the application did the same after the messages had traversed an interprocess communication scheme).


Summaries of Call Center Programming Elements

Call center functionality is a feature of the Telephony Application Programming Interface (TAPI) version 3.0. The programming elements appearing in the TAPI 2.2 information set support a TAPI 3.0 call center. For information on call centers, see About TAPI 3.0 Call Center Controls.

The TAPI 2.2 call center programming element summaries are as follows:

  • Call Center Functions
  • Call Center Structures
  • Call Center Messages
  • Call Center Constants


Phone Devices Overview

Phone device support is supplementary rather than basic, so service providers are not required to support phone devices.

Just as a line device class is an abstraction of a physical line device, the phone device class represents a device-independent abstraction of a telephone set. TAPI treats line and phone devices as devices that are independent of each other. In other words, you can use a phone (device) without using an associated line, and you can use a line (device) without using a phone.

Service providers that fully implement this independence can offer uses for these devices not defined by traditional telephony protocols. For example, a person can use the handset of the desktop's phone as a waveform audio device for voice recording or playback, perhaps without the switch's knowledge that the phone is in use. In such an implementation, lifting the local phone handset need not automatically send an offhook signal to the switch.

This independence also allows an application to ring the local telephone in a manner that is independent of incoming calls. The capabilities of service providers are limited by the capabilities of the hardware and software used to interconnect the switch, the phone, and the computer.

TAPI includes functions to retrieve device capabilities that allow clients to determine whether such a usage model is supported.

This section describes phone devices and explains how to use the TAPI phone functions to access these devices.

  • The Phone Device
  • Initialization and Shutdown


The Phone Device

A phone device is a device that supports the phone device class and that includes some or all of the following elements:

  • Hookswitch/transducer This is a means for audio input and output. TAPI recognizes that a phone device can have several transducers, which can be activated and deactivated (taken offhook or placed onhook) under application or manual user control. TAPI identifies three types of hookswitch devices common to many phone sets:

    Handset The traditional mouth-and-ear piece combination that must be manually lifted from a cradle and held against the user's ear.

    Speakerphone Enables the user to conduct calls hands-free. The hookswitch state of a speakerphone can usually be changed both manually and by the API. The speakerphone can be internal or external to the phone device. The speaker part of a speakerphone allows multiple listeners.

    Headset Enables the user to conduct calls hands-free. The hookswitch state of a headset can usually be changed both manually and by the API.

    A hookswitch must be offhook to allow audio data to be sent to and/or received by the corresponding transducer.

  • Volume Control/Gain Control/Mute: Each hookswitch device is the pairing of a speaker and a microphone component. The API provides for volume control and muting of speaker components and for gain control or muting of microphone components.
  • Ringer: A means for alerting users, usually through a bell. A phone device may be able to ring in a variety of modes or patterns.
  • Display : A mechanism for visually presenting messages to the user. A phone display is characterized by its number of rows and columns.
  • Phone buttons : An array of buttons. Whenever the user presses a button on the phone set, the API reports that the corresponding button was pressed. Button-lamp identifiers identify a button and lamp pair. Of course, it is possible to have button-lamp pairs with either no button or no lamp. Button-lamp identifiers are integer values that range from 0 to the maximum number of button-lamps available on the phone device, minus one. Each button belongs to a button class. Classes include call appearance buttons, feature buttons, keypad buttons, and local buttons.
  • Lamps : An array of lamps (such as LEDs) individually controllable from the API. Lamps can be lit in different modes by varying the on and off frequency. The button-lamp identifier identifies the lamp.
  • Data areas : Memory areas in the phone device where instruction code or data can be downloaded to and/or uploaded from. The downloaded information would affect the behavior (or in other words, program) the phone device.

TAPI allows an application to monitor and control elements of the phone device. The most useful elements for an application are the hookswitch devices. The phone set can act as an audio I/O device (to the computer) with volume control, gain control and mute, a ringer (for alerting the user), data areas (for programming the phone), and perhaps a display, though the computer's display is more capable. The application writer is discouraged from directly controlling or using phone lamps or phone buttons, because lamp and button capabilities can vary widely among phone sets, and applications can quickly become tailored to specific phone sets.

There is no guaranteed core set of services supported by all phone devices as there is for line devices (the Basic Telephony services). Therefore, before an application can use a phone device, the application must first determine the exact capabilities of the phone device. Telephony capability varies with the configuration (client versus client/server), the telephone hardware, and the service-provider software. Applications should make no assumptions as to what telephony capabilities are available. An application determines the device capabilities of a phone device by calling the phoneGetDevCaps function. A phone's device capabilities indicate which of these elements exist for each phone device present in the system and what their capabilities are. Although strongly oriented toward real-life telephone sets, this abstraction can provide a meaningful implementation (or subset thereof) for other devices as well. Take as an example a separate headset directly connected and controllable from the computer and operated as a phone device. Hookswitch changes can be triggered by detection of voice energy (offhook) or a period of silence (onhook); ringing can be emulated by the generation of an audible signal into the headset; a display can be emulated through text-to-speech conversion.

A phone device need not be realized in hardware, but can instead be emulated in software using a mouse- or keyboard-driven graphical command interface and the computer's speaker or sound system. Such a "soft phone" can be an application that uses TAPI. It can also be a service provider, which can be listed as a phone device available to other applications through the API, and as such is assigned a phone device identifier.

Depending on the environment and configuration, phone sets can be shared devices between the application and the switch. Some minor provision is made in the API where the switch can temporarily suspend the API's control of a phone device.


Initialization and Shutdown

For an application to use any of TAPI's 30 supplementary phone functions, it needs a connection to TAPI, through which it can receive messages. The application establishes this connection using the phoneInitializeEx function. In this function, the application specifies the notification mechanism by which TAPI informs the application of changes in the state of the phone and of asynchronous completion of phone functions.

The phoneInitializeEx function returns two pieces of information to the application: an application handle, and the number of phone devices. The application handle represents the application's usage of TAPI. The TAPI functions that use phone handles do not require the application handle, as this handle is derived from the specified phone handle.

The second piece of information returned by phoneInitializeEx is the number of phone devices available to TAPI. Phone devices are identified by their device identifier (device ID). Valid device identifiers range from zero to the number of phone devices minus one. For example, if phoneInitializeEx reports that there are two phone devices in a system, then valid phone device identifiers are 0 and 1. After an application is finished using the phone functions of TAPI, it invokes phoneShutdown, passing its application handle to shut down its usage of TAPI. This allows TAPI to free any resources assigned to the application.

Applications should not invoke phoneInitializeEx without subsequently opening a phone (at least for monitoring). If the application is not monitoring and not using any devices, it should call phoneShutdown so that memory resources allocated by the TAPI dynamic-link library can be released if unneeded, and the library itself can be unloaded from memory while not needed.

Both phoneInitializeEx and phoneShutdown operate synchronously. That is, these functions either return a success or failure indication, and never return an asynchronous request identifier.


Opening and Closing Phone Devices

After determining the capabilities of a phone device, an application must open the device before it can access functions on that phone. After a phone device has been successfully opened, the application is returned a handle representing the open phone. A phone device can be opened in different modes, thus providing a structured way of sharing a phone device.

The phoneOpen function opens the specified phone device to give the application access to functions on the phone. A phone device is identified to phoneOpen by means of its device identifier, which is passed as the dwDeviceID parameter.


Operating Modes and Privileges

The application can request one of two operating modes when opening a phone device. These modes reflect the privileges the application requests for the device:

  • Opening a phone for monitor privileges lets the application determine the status of the phone device. Messages are sent to the application when status changes on the phone device are detected.
  • An application that opens a phone device for owner privileges can use operations that modify the state of the phone device. Owner privilege automatically includes full monitor privileges as well. At any time, a given phone device can be open only once for owner privileges, but multiple times for monitor privileges. All phoneSet operations require owner privileges, while all phoneGet operations require only monitor privileges.


Device IDs

Other TAPI phone functions use a handle to an open phone device to identify the open phone device. The only functions for phone devices that take a phone device identifier parameter (as opposed to a phone handle) are the phoneGetDevCaps and phoneOpen functions. An application can retrieve the phone's device identifier by using the phoneGetID function with the phone handle as a parameter.

An application can also obtain device identifiers for various device classes associated with an opened phone by invoking phoneGetID. See TAPI Device Classes for device class names.

This function takes a phone handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open phone device. If the device class is "tapi/phone", the device identifier of the phone device is returned.

In contrast with line devices, for which the basic line services provide the equivalent of POTS, no minimum guaranteed set of functions is defined for phone devices. While each phone device provides at least the functions and messages described in this section, they do not offer any actual operations on the physical phone device.


Closing the Phone Device

The phoneClose function closes the specified phone device. The phone device can also be forcibly closed after the user has modified the configuration of that phone or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), then a service provider can forcibly close the phone device.

These messages can also be sent unsolicited as a result of the phone device being reclaimed in some other manner. An application should therefore be prepared to handle unsolicited PHONE_CLOSE messages. At the time the phone device is closed, any outstanding asynchronous replies pertaining to that device are suppressed.


Hookswitch Devices

A phone device can have multiple hookswitch devices. A hookswitch is the switch that connects or disconnects a device from the phone line. On a telephone, for example, this is the switch that is automatically activated when a user lifts the receiver from the cradle to get a new dial tone. TAPI defines three types of hookswitch devices for a phone: handset, speakerphone, and headset. Each hookswitch device has a speaker and a microphone component, and operates in one of four hookswitch modes:

  • Onhook The hookswitch device is onhook, and both its microphone and speaker are disabled.
  • Microphone only The hookswitch device is offhook, its microphone is enabled, and its speaker is mute.
  • Speaker only The hookswitch device is offhook, its microphone is mute, and its speaker is enabled.
  • Microphone and speaker The hookswitch device is offhook, and both microphone and speaker are enabled.

The phoneSetHookSwitch function is used to set the hookswitch mode of one or more of the hookswitch devices of an open phone device. For example, to mute or unmute the microphone or speaker component of a hookswitch device, use phoneSetHookSwitch with the appropriate hookswitch mode. The phoneGetHookSwitch function can be used to query the hookswitch mode of a hookswitch device of an open phone device.

When the mode of a phone's hookswitch device is changed manually, for example by lifting the handset from its cradle, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.

The volume of the speaker component of a hookswitch device can be set with phoneSetVolume. Volume setting is different from mute in that muting a speaker and later unmuting it will preserve the volume setting of the speaker. The phoneGetVolume function can be used to return the current volume setting of a hookswitch device's speaker of an open phone device.

The microphone component of a hookswitch device can also be gain controlled. Gain setting is different from mute in that muting a microphone and later unmuting it will preserve the gain setting of the microphone. Use phoneSetGain to set the gain of a hookswitch device's microphone of an open phone device, and phoneGetGain to return the gain setting of a hookswitch device's microphone of an opened phone.

When the volume or gain of a phone's hookswitch device is changed, a PHONE_STATE message is sent to the application function to notify the application about the state change. Parameters to this message provide an indication of the change.


Display

TAPI provides access to a phone's display. The display is modeled as an alphanumeric area with rows and columns. A phone's device capabilities indicate the size of a phone's display as the number of rows and the number of columns. Both these numbers are zero if the phone device does not have a display. Use phoneSetDisplay to write information to the display of an open phone device, and phoneGetDisplay to retrieve the current contents of a phone's display.

When the display of a phone device is changed, a PHONE_STATE message is sent to the application function to notify the application about the state change. Parameters to this message provide an indication of the change.


Ring

A single phone may be able to ring with different ring modes. Given the wide variety of ring modes available, ring modes are identified by means of their ring mode number. A ring mode number ranges from zero to the number of available ring modes minus one.

The functions an application would use to control a phone device's ring modes are phoneSetRing, which rings an open phone device according to a given ring mode, and phoneGetRing, which returns the current ring mode of an opened phone device.

When the ring mode of a phone device is changed, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.


Phone Buttons

TAPI models a phone's buttons and lamps as button-lamp pairs. A button with no lamp next to it or a lamp with no button is specified using a "dummy" indicator for the missing lamp or button. A button with multiple lamps is modeled by using multiple button-lamp pairs.

Information associated with a phone button can be set and retrieved. When a button is pressed, a PHONE_BUTTON message is sent to the application function. The parameters of this message are a handle to the phone device and the button-lamp identifier of the button that was pressed. The keypad buttons '0' through '9', '*', and '#' are assigned the fixed button-lamp identifiers 0 through 11.

The functions associated with buttons are phoneSetButtonInfo, which sets the information associated with a button on a phone device, and phoneGetButtonInfo, which returns information associated with a button on a phone device. The PHONE_BUTTON message is sent to an application when a button on the phone is pressed.

The information associated with a button does not carry any semantic meaning as far as TAPI is concerned. It is useful for device-specific applications that understand the meaning of this information for a given phone device, or for display to the user, such as online help.


Lamps

The lamps on a phone device can be lit in a variety of different lighting modes. Unlike ringing patterns, lamp modes are more uniform across phone sets of different vendors. A common set of lamp modes is defined by the API. A lamp identified by its lamp-button identifier can be lit in a given lamp mode. A lamp can also be queried for its current lamp mode.

The TAPI functions used for lamps are phoneSetLamp, which lights a lamp on a specified open phone device in a given lamp lighting mode, and phoneGetLamp, which returns the current lamp mode of the specified lamp.

When a lamp of a phone device is changed, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.


Data Areas

Some phone sets support the notion of downloading data from or uploading data to the phone device, which allows the phone set to be programmed in a variety of ways. TAPI models these phone sets as having one or more download or upload areas. Each area is identified by a number that ranges from zero to the number of data areas available on the phone minus one. Sizes of each area can vary. The format of the data itself is device-specific.

The TAPI phoneSetData function downloads a buffer of data to a given data area in the phone device, and the phoneGetData function uploads the contents of a given data area in the phone device to a buffer.

When a data area of a phone device is changed, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.


Status

Most of the get and set operations deal with one component of information only. The phoneGetStatus function returns complete status information about a phone device to an application.

As mentioned earlier, whenever a status item changes on the phone device, a PHONE_STATE message is sent to the application function. This message's parameters include a handle to the phone device and an indication of the status item that changed.

An application can use phoneSetStatusMessages to select the specific status changes for which it wants to be notified. Correspondingly, phoneGetStatusMessages returns the status changes for which the application wants to be notified.


Extended Telephony Phone Functions

The Extended phone services (or Device-Specific phone services) include all extensions to the TAPI defined by the service provider. TAPI defines a mechanism that enables service-provider vendors to extend TAPI using device-specific extensions. TAPI defines only the extension mechanism, and by doing so provides access to device-specific extensions. TAPI does not define their behavior, which is completely defined by the service provider.

TAPI consists of scalar and bit-flag data constant definitions, data structures, functions, and messages. Procedures are defined that enable a vendor to extend most of these, as described in the following topics.

  • Scalar Data Constants
  • Bit-Flag Data Constants
  • Functions and Messages


Scalar Data Constants

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. Because most data constants are DWORDs, the range 0x00000000 through 0x7FFFFFFF is typically reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF is available for vendor-specific extensions. The assumption is that a vendor would define values that are natural extensions of the datatypes defined by the API.


Bit-Flag Data Constants

For extensible bit-flag data constants, a service-provider vendor can define new values for specified bits. Because most bit-flag constants are DWORDs, a specific number of the lower bits are usually reserved for common extensions, while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up, and vendor-specific extensions should be assigned from bit 31 down. This scheme provides maximum flexibility in assigning bit positions to common extensions, as opposed to vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by the API.

Extensible data structures have a variably sized field that is reserved for device-specific use. Because the field is variably sized, the service provider decides the field's amount of information and interpretation. A vendor that defines a device-specific field is expected to make these natural extensions of the original data structure defined by the API.


Functions and Messages

The phoneDevSpecific function and its associated PHONE_DEVSPECIFIC message enable an application to access device-specific phone features that are unavailable through the common telephony services for phones. In other words, phoneDevSpecific is the device-specific escape function that allows vendor-dependent extensions, and PHONE_DEVSPECIFIC is the device-specific message that is sent to the application.

The parameter profile of the phoneDevSpecific function is generic in that little interpretation of the parameters is made by TAPI. Rather, the interpretation of the parameters is defined by the service provider and must be understood by an application that uses them. The parameters are simply passed through by TAPI from the application to the service provider. An application that relies on device-specific extensions will usually not work with other service providers, but applications written to the common telephony phone services will work with the extended service provider.


TAPI 2.2 Reference

This section describes the TAPI elements necessary for writing a telephony application, namely:

TAPI Quick Function Reference

TAPI Unicode Support

TAPI Functions

TAPI Structures

TAPI Messages

TAPI Constants

TAPI Device Classes


TAPI Quick Function Reference

The following hyperlinked summary of TAPI functions is organized by category of operation. For additional information, see the overviews for Assisted Telephony and Service Levels.

Reference section | Description
Basic Telephony Services Reference | Functions associated with POTS-level telephony tasks, such as lineMakeCall.
Supplementary Telephony Services Reference | Functions with more advanced features, such as call redirect.
Extended Telephony Services Reference | Functions that allow access to service provider-specific functions not directly defined by TAPI.
Assisted Telephony Services Reference | Functions that allow any Microsoft® Win32®-based application to establish voice calls and media calls, such as in using a phone dialer.


Basic Telephony Services Reference

The Basic Telephony functions are listed by category in the following tables. A function is identified as asynchronous if it indicates completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.

Following is a functional grouping of the basic telephony service functions:

Address Formats

Addresses

Answering Incoming Calls

Call Drop Functions

Call Handle Manipulation

Call Privilege Control

Call States and Events

Line Status and Capabilities

Line Version Negotiation

Location and Country/Region Information

Making Calls

Opening and Closing Line Devices

Request Recipient Services

TAPI Initialization and Shutdown

Toll Saver Support

TAPI Initialization and Shutdown

Function | Description
lineInitializeEx | Initializes the TAPI line abstraction for use by the invoking application. Synchronous.
lineShutdown | Shuts down the application's use of TAPI's line abstraction. Synchronous.

Line Version Negotiation

Function | Description
lineNegotiateAPIVersion | Allows an application to negotiate a TAPI version to use. Synchronous.

Line Status and Capabilities

Function | Description
lineGetDevCaps | Returns the capabilities of a given line device. Synchronous.
lineGetDevConfig | Returns configuration of a media stream device. Synchronous.
lineGetLineDevStatus | Returns current status of the specified open line device. Synchronous.
lineSetDevConfig | Sets the configuration of the specified media stream device. Synchronous.
lineSetStatusMessages | Specifies the status changes for which the application needs to be notified. Synchronous.
lineGetStatusMessages | Returns the application's current line and address status message settings. Synchronous.
lineGetID | Retrieves a device ID associated with the specified open line, address, or call. Synchronous.
lineGetIcon | Allows an application to retrieve an icon for display to the user. Synchronous.
lineConfigDialog | Causes the provider of the specified line device to display a dialog box that allows the user to configure parameters related to the line device. Synchronous.
lineConfigDialogEdit | Displays a dialog box allowing the user to change configuration information for a line device. Synchronous.

Addresses

Function | Description
lineGetAddressCaps | Returns the telephony capabilities of an address. Synchronous.
lineGetAddressStatus | Returns current status of a specified address. Synchronous.
lineGetAddressID | Retrieves the address ID of an address specified using an alternate format. Synchronous.

Opening and Closing Line Devices

Function | Description
lineOpen | Opens a specified line device for providing subsequent monitoring and/or control of the line. Synchronous.
lineClose | Closes a specified opened line device. Synchronous.

Address Formats

Function | Description
lineTranslateAddress | Translates between an address in canonical format and an address in dialable format. Synchronous.
lineSetCurrentLocation | Sets the location used as the context for address translation. Synchronous.
lineSetTollList | Manipulates the toll list. Synchronous.
lineGetTranslateCaps | Returns address translation capabilities. Synchronous.

Call States and Events

Function | Description
lineGetCallInfo | Returns fixed information about a call. Synchronous.
lineGetCallStatus | Returns complete call status information for the specified call. Synchronous.
lineSetAppSpecific | Sets the application-specific field of a call's information structure. Synchronous.

Making Calls

Function | Description
lineMakeCall | Makes an outbound call and returns a call handle for it. Asynchronous.
lineDial | Dials (parts of one or more) dialable addresses. Asynchronous.

Answering Incoming Calls

Function | Description
lineAnswer | Answers an incoming call. Asynchronous.

Toll Saver Support

Function | Description
lineSetNumRings | Indicates the number of rings after which incoming calls are to be answered. Synchronous.
lineGetNumRings | Returns the minimum number of rings requested with lineSetNumRings. Synchronous.

Call Privilege Control

Function | Description
lineSetCallPrivilege | Sets the application's privilege to the privilege specified. Synchronous.

Call Drop Functions

Function | Description
lineDrop | Disconnects a call, or abandons a call attempt in progress. Asynchronous.
lineDeallocateCall | Deallocates the specified call handle. Synchronous.

Call Handle Manipulation

Function | Description
lineHandoff | Hands off call ownership and/or changes an application's privileges to a call. Synchronous.
lineGetNewCalls | Returns call handles to calls on a specified line or address for which the application does not yet have handles. Synchronous.
lineGetConfRelatedCalls | Returns a list of call handles that are part of the same conference call as the call specified as a parameter. Synchronous.


Location and Country/Region Information

Function | Description
lineTranslateDialog | Displays a dialog box allowing the user to change location and calling card information. Synchronous.
lineGetCountry | Retrieves dialing rules and other information about a given country/region. Synchronous.

Request Recipient Services

The following two functions are used only in support of Assisted Telephony.

Function | Description
lineRegisterRequestRecipient | Registers or deregisters the application as a request recipient for the specified request mode. Synchronous.
lineGetRequest | Gets the next request from the Telephony dynamic link library. Synchronous.


Supplementary Telephony Services Reference

The Supplementary Telephony functions are listed by category in the following topics.

Supplementary Line Service Functions

Supplementary Phone Service Functions


Supplementary Line Service Functions

The supplementary line service functions are listed by category in the following topics. A function is identified as asynchronous if it will indicate completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.

Following is a functional grouping of the supplementary line service functions:

Agents

Application priority

Bearer mode and rate

Call accept and redirect

Call completion

Call conference

Call forwarding

Call hold

Call park

Call pickup

Call reject

Call transfer

Digit monitoring and gathering

Generating inband digits and tones

Making calls

Media control

Media monitoring

Proxies

Quality of Service

Sending information to remote party

Service provider management

Setting a terminal for phone conversations

Tone monitoring

and other miscellaneous supplementary line service functions.

Bearer Mode and Rate

Function | Description
lineSetCallParams | Requests a change in the call parameters of an existing call. Synchronous.

Media Monitoring

Function | Description
lineMonitorMedia | Enables or disables media mode notification on a specified call. Synchronous.

Digit Monitoring and Gathering

Function | Description
lineMonitorDigits | Enables or disables digit detection notification on a specified call. Synchronous.
lineGatherDigits | Performs the buffered gathering of digits on a call. Synchronous.

Tone Monitoring

Function | Description
lineMonitorTones | Specifies which tones to detect on a specified call. Synchronous.

Media Control

Function | Description
lineSetMediaControl | Sets up a call's media stream for media control. Synchronous.
lineSetMediaMode | Sets the media mode(s) of the specified call in its LINECALLINFO structure. Synchronous.

Generating Inband Digits and Tones

Function | Description
lineGenerateDigits | Generates inband digits on a call. Synchronous.
lineGenerateTone | Generates a given set of tones inband on a call. Synchronous.

Call Accept and Redirect

Function | Description
lineAccept |  | Accepts an offered call and starts alerting both caller (ringback) and called party (ring). Asynchronous.
lineRedirect |  | Redirects an offering call to another address. Asynchronous.

Call Reject

Function | Description
lineDrop |  | Disconnects a call, or abandons a call attempt in progress. Asynchronous.

Call Hold

Function | Description
lineHold |  | Places the specified call on hard hold. Asynchronous.
lineUnhold |  | Retrieves a held call. Asynchronous.

Securing Calls

Function | Description
lineSecureCall |  | Secures an existing call from interference by other events such as call-waiting beeps on data connections. Asynchronous.

Call Transfer

Function | Description
lineSetupTransfer |  | Prepares a specified call for transfer to another address. Asynchronous.
lineCompleteTransfer |  | Transfers a call that was set up for transfer to another call, or enters a three-way conference. Asynchronous.
lineBlindTransfer |  | Transfers a call to another party. Asynchronous.
lineSwapHold |  | Swaps the active call with the call currently on consultation hold. Asynchronous.

Call Conference

Function | Description
lineSetupConference |  | Prepares a given call for the addition of another party. Asynchronous.
linePrepareAddToConference |  | Prepares to add a party to an existing conference call by placing the conference call in a hold state and creating a consultation call that can be added later to the conference call. Asynchronous.
lineAddToConference |  | Adds a consultation call to an existing conference call. Asynchronous.
lineRemoveFromConference |  | Removes a party from a conference call. Asynchronous.

Call Park

Function | Description
linePark |  | Parks a given call at another address. Asynchronous.
lineUnpark |  | Retrieves a parked call. Asynchronous.

Call Forwarding

Function | Description
lineForward |  | Sets or cancels call forwarding requests. Asynchronous.

Call Pickup

Function | Description
linePickup |  | Picks up a call alerting at a specified destination address and returns a call handle for the picked-up call (linePickup can also be used for call waiting). Asynchronous.

Sending Information to Remote Party

Function | Description
lineReleaseUserUserInfo |  | Releases user-user information, permitting the system to overwrite this storage with new information. Asynchronous.
lineSendUserUserInfo |  | Sends user-user information to the remote party on the specified call. Asynchronous.

Call Completion

Function | Description
lineCompleteCall |  | Places a call completion request. Asynchronous.
lineUncompleteCall |  | Cancels a call completion request. Asynchronous.

Setting a Terminal for Phone Conversations

Function | Description
lineSetTerminal |  | Specifies the terminal device to which the specified line, address events, or call media stream events are routed. Asynchronous.

Application Priority

Function | Description
lineGetAppPriority |  | Retrieves handoff and/or Assisted Telephony priority information for an application. Synchronous.
lineSetAppPriority |  | Sets the handoff and/or Assisted Telephony priority for an application. Synchronous.

Service Provider Management

Function | Description
lineAddProvider |  | Installs a telephony service provider. Synchronous.
lineConfigProvider |  | Displays configuration dialog box of a service provider. Synchronous.
lineRemoveProvider |  | Removes an existing telephony service provider. Synchronous.
lineGetProviderList |  | Retrieves a list of installed service providers. Synchronous.

Agents

Function | Description
lineAgentSpecific |  | Allows the application to access proprietary handler-specific functions of the agent handler associated with the address. Asynchronous.
lineGetAgentActivityList |  | Obtains the list of activities from which an application selects the functions an agent is performing. Asynchronous.
lineGetAgentCaps |  | Obtains the agent-related capabilities supported on the specified line device. Asynchronous.
lineGetAgentGroupList |  | Obtains the list of agent groups into which an agent can log into on the automatic call distributor. Asynchronous.
lineGetAgentStatus |  | Obtains the agent-related status on the specified address. Asynchronous.
lineSetAgentActivity |  | Sets the agent activity code associated with a particular address. Asynchronous.
lineSetAgentGroup |  | Sets the agent groups that the agent is logged into on a particular address. Asynchronous.
lineSetAgentState |  | Sets the agent state associated with a particular address. Asynchronous.

Proxies

Function | Description
lineProxyMessage |  | Used by a registered proxy request handler to generate TAPI messages. Synchronous.
lineProxyResponse |  | Indicates completion of a proxy request by a registered proxy handler. Synchronous.

Quality of Service

Function | Description
lineSetCallQualityOfService |  | Requests a change of the quality of service parameters for an existing call. Asynchronous.

Miscellaneous

Function | Description
lineSetCallData |  | Sets the CallData member of the LINECALLINFO structure. Asynchronous.
lineSetCallTreatment |  | Sets the sounds that the user hears when a call is unanswered or on hold. Asynchronous.
lineSetLineDevStatus |  | Sets the line device status. Asynchronous.


Supplementary Phone Service Functions

The supplementary phone service functions are listed by category in the following topics. A function is identified as asynchronous if it will indicate completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.

Following is a functional grouping of the supplementary phone service functions:

Buttons

Data areas

Display

Hookswitch devices

Lamps

Opening and closing phone devices

Phone initialization and shutdown

Phone status and capabilities

Phone version negotiation

Ring

Status

Phone Initialization and Shutdown

Function | Description
phoneInitializeEx | Initializes TAPI phone abstraction for use by the invoking application. Synchronous.
phoneShutdown | Shuts down an application's use of TAPI's phone abstraction. Synchronous.

Phone Version Negotiation

Function | Description
phoneNegotiateAPIVersion | Allows an application to negotiate a TAPI version to use. Synchronous.

Opening and Closing Phone Devices

Function | Description
phoneOpen | Opens the specified phone device, giving the application either owner or monitor privileges. Synchronous.
phoneClose | Closes a specified open phone device. Synchronous.

Phone Status and Capabilities

Function | Description
phoneGetDevCaps | Returns the capabilities of a given phone device. Synchronous.
phoneGetID | Returns a device ID for the given device class associated with the specified phone device. Synchronous.
phoneGetIcon | Allows an application to retrieve an icon for display to the user. Synchronous.
phoneConfigDialog | Causes the provider of the specified phone device to display a dialog box that allows the user to configure parameters related to the phone device. Synchronous.

Hookswitch Devices

Function | Description
phoneSetHookSwitch | Sets the hook state of an open phone's hookswitch devices to a specified mode. Asynchronous.
phoneGetHookSwitch | Queries the hookswitch mode of a hookswitch device of an open phone device. Synchronous.
phoneSetVolume | Sets the volume of a hookswitch device's speaker of an open phone device. Asynchronous.
phoneGetVolume | Returns the volume setting of a hookswitch device's speaker of an open phone device. Synchronous.
phoneSetGain | Sets the gain of a hookswitch device's mic of an open phone device. Asynchronous.
phoneGetGain | Returns the gain setting of a hookswitch device's mic of an open phone. Synchronous.

Display

Function | Description
phoneSetDisplay | Writes information to the display of an open phone device. Asynchronous.
phoneGetDisplay | Returns the current contents of a phone's display. Synchronous.

Ring

Function | Description
phoneSetRing | Rings an open phone device according to a given ring mode. Asynchronous.
phoneGetRing | Returns the current ring mode of an opened phone device. Synchronous.

Buttons

Function | Description
phoneSetButtonInfo | Sets the information associated with a button on a phone device. Asynchronous.
phoneGetButtonInfo | Returns information associated with a button on a phone device. Synchronous.

Lamps

Function | Description
phoneSetLamp | Lights a lamp on a specified open phone device in a given lamp lighting mode. Asynchronous.
phoneGetLamp | Returns the current lamp mode of the specified lamp. Synchronous.

Data Areas

Function | Description
phoneSetData | Downloads a buffer of data to a given data area in the phone device. Asynchronous.
phoneGetData | Uploads the contents of a given data area in the phone device to a buffer. Synchronous.

Status

Function | Description
phoneSetStatusMessages | Specifies the status changes for which the application wants to be notified. Synchronous.
phoneGetStatusMessages | Returns the status changes for which the application wants to be notified. Synchronous.
phoneGetStatus | Returns the complete status of an open phone device. Synchronous.


Extended Telephony Services Reference

The Extended Telephony functions are listed by category in the following tables.

Extended Telephony Functions for Line Devices

Function | Description
lineNegotiateExtVersion | Allows an application to negotiate an extension version to use with the specified line device. Asynchronous.
lineDevSpecific | Gives service providers access to device-specific features not offered by other TAPI functions. Synchronous.
lineDevSpecificFeature | Sends device-specific switch features to the switch. Asynchronous.

Extended Telephony Functions for Phone Devices

Function | Description
phoneDevSpecific | Device-specific escape function to allow vendor-dependent extensions. Asynchronous.
PhoneNegotiateExtVersion | Allows an application to negotiate an extension version to use with the specified phone device. Synchronous.


Assisted Telephony Services Reference

The Assisted Telephony functions are listed in the following table. Assisted Telephony functions allow any Win32-based application to establish voice calls and media calls. For background information, see the Assisted Telephony overview.

Assisted Telephony Services Functions

Function | Description
tapiRequestMakeCall | Submits a request to place a voice call.
tapiRequestMediaCall | Obsolete. Do not use.
tapiRequestDrop | Obsolete. Do not use.
tapiGetLocationInfo | Returns codes identifying the country/region and city/area.


TAPI Unicode Support

The following section contains information about support for Unicode.

  • Functions with Unicode (W) Versions
  • Functions without Unicode Versions


Functions with Unicode (W) Versions

The following TAPI functions are implemented in Unicode (W) and ANSI (A) versions. In general, the implementation of the ANSI version calls the Unicode version and performs necessary conversions of ANSI parameters and structure fields to and from Unicode; the following table indicates the parameters that are converted.

Applications that explicitly call the generic (neither "W" or "A" suffix) version of a function will execute the ANSI version, for compatibility with previous versions of TAPI.

Note The entire Telephony Service Provider Interface (TSPI) is Unicode for version 2.0.

In the following table, references to string fields in TAPI structures consist of a portion of the field names. For example, the "Caller Address" in the LINEFORWARD structure is pointed to by a field named dwCallerAddressOffset and delimited by a field named dwCallerAddressSize; in the table, this string is identified simply as CallerAddress.

TAPI function | Parameters and structure fields converted in ANSI version of function
lineAddProvider | lpszProviderName
lineBlindTransfer | lpszDestAddress
lineConfigDialog | lpszDeviceClass
lineConfigDialogEdit lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceConfigIn and lpDeviceConfigOut, if these are directly manipulated.

lineDial | lpszDestAddress
lineForward lpForwardList (LINEFORWARDLIST)
  • ForwardList (LINEFORWARD)
    • CallerAddress
    • DestAddress

lpCallParams (LINECALLPARAMS)

  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineGatherDigits lpsDigits

lpszTerminationDigits

lineGenerateDigits | lpszDigits
lineGetAddressCaps lpAddressCaps (LINEADDRESSCAPS)
  • Address
  • CompletionMsgText
  • DeviceClasses
  • CallTreatmentList (LINECALLTREATMENTENTRY)
  • CallTreatmentName
lineGetAddressID | lpsAddress
lineGetAddressStatus lpAddressStatus (LINEADDRESSSTATUS)
  • Forward (LINEFORWARD)
  • CallerAddress
  • DestAddress
lineGetAgentActivityList lpAgentActivityList (LINEAGENTACTIVITYLIST)
  • List (LINEAGENTACTIVITYENTRY)
  • Name
lineGetAgentCaps lpAgentCaps (LINEAGENTCAPS)
  • AgentHandlerInfo
lineGetAgentGroupList lpAgentGroupListI(LINEAGENTGROUPLIST)
  • List (LINEAGENTGROUPENTRY)
  • Name
lineGetAgentStatus lpAgentStatus (LINEAGENTSTATUS)
  • Activity
  • GroupList (LINEAGENTGROUPENTRY)
  • Name
lineGetAppPriority lpszAppFilename

lpExtensionName

lineGetCallInfo lpCallInfo (LINECALLINFO)
  • CallerID
  • CallerIDName
  • CalledID
  • CalledIDName
  • ConnectID
  • ConnectedIDName
  • RedirectionID
  • RedirectionIDName
  • RedirectingID
  • RedirectingIDName
  • AppName
  • DisplayableAddress
  • CalledParty
  • Comment
lineGetCountry lpLineCountryList (LINECOUNTRYLIST)
  • CountryList (LINECOUNTRYENTRY)
  • CountryName
  • SameAreaRule
  • LongDistanceRule
  • InternationalRule
lineGetDevCaps lpLineDevCaps (LINEDEVCAPS)
  • ProviderInfo
  • SwitchInfo
  • LineName
  • TerminalText
  • DeviceClasses

Note dwStringFormat is obsolete.

LineGetDevConfig lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceConfig, if these are directly manipulated.

LineGetIcon | lpszDeviceClass
lineGetID lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceID, if these are directly manipulated.

LineGetLineDevStatus lpLineDevStatus (LINEDEVSTATUS)
  • AppInfo (LINEAPPINFO)
  • MachineName
  • UserName
  • ModuleFilename
  • FriendlyName
lineGetProviderList lpProviderList (LINEPROVIDERLIST)
  • ProviderList (LINEPROVIDERENTRY)
  • ProviderFilename
lineGetRequest lpRequestBuffer (LINEREQMAKECALL
  • szDestAddress
  • szAppName
  • szCalledParty
  • szComment
lineGetTranslateCaps lpTranslateCaps (LINETRANSLATECAPS)
  • CardList (LINECARDENTRY)
  • CardName
  • SameAreaRule
  • LongDistanceRule
  • InternationalRule
  • LocationList (LINELOCATIONENTRY
  • LocationName
  • CityCode
  • LocalAccessCode
  • LongDistanceAccessCode
  • TollPrefixList
  • celCallWaiting
lineHandoff | lpszFileName
lineInitializeEx | lpszFriendlyAppName
lineMakeCall lpszDestAddress

lpCallParams (LINECALLPARAMS)

  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineOpen lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
linePark lpszDirAddress

lpNonDirAddress (VARSTRING)

  • String
linePickup lpszDestAddress

lpszGroupID

linePrepareAddToConference lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineRedirect | lpszDestAddress
lineSetAppPriority lpszAppFilename

lpszExtensionName

lineSetDevConfig lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceConfig, if these are directly manipulated.

lineSetTollList | lpszAddressIn
lineSetupConference lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineSetupTransfer lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineTranslateAddress lpszAddressIn

lpTranslateOutput (LINETRANSLATEOUTPUT)

  • DialableString
  • DisplayableString
lineTranslateDialog | lpszAddressIn
lineUnpark | lpszDestAddress
phoneConfigDialog | lpszDeviceClass
phoneGetButtonInfo lpButtonInfo (PHONEBUTTONINFO)
  • ButtonText
phoneGetDevCaps lpPhoneCaps (PHONECAPS)
  • ProviderInfo
  • PhoneInfo
  • PhoneName
  • DeviceClasses

Note dwStringFormat is obsolete.

phoneGetIcon | lpszDeviceClass
phoneGetID lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceID, if these are directly manipulated.

phoneGetStatus lpPhoneStatus (PHONESTATUS)
  • OwnerName
phoneInitializeEx | lpszFriendlyAppName
phoneSetButtonInfo lpButtonInfo (PHONEBUTTONINFO)
  • ButtonTest
tapiGetLocationInfo lpszCountryCode

lpszCityCode

tapiRequestMakeCall lpszDestAddress

lpszAppName

lpszCalledParty

lpszComment


Functions without Unicode Versions

The following functions are provided only in a generic version without an "A" or "W" suffix.

TAPI function | Comments
lineAccept | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineAddToConference | —
lineAgentSpecific | The memory pointed to by lpParams is private between the application and agent handler. The application must provide data in the form specified in the agent handler extension definition.
lineAnswer | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineClose | —
lineCompleteCall | —
lineCompleteTransfer | —
lineConfigProvider | —
lineDeallocateCall | —
lineDevSpecific | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
lineDevSpecificFeature | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
lineDrop | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineGenerateTone | —
lineGetCallStatus | —
lineGetConfRelatedCalls | —
lineGetNewCalls | —
lineGetMessage | —
lineGetNumRings | —
lineGetStatusMessages | —
lineHold | —
lineMonitorDigits | —
lineMonitorMedia | —
lineMonitorTones | —
lineNegotiateAPIVersion | —
lineNegotiateExtVersion | —
lineProxyMessage | —
lineProxyResponse | The fields in the LINEPROXYREQUEST structure are always Unicode.
lineRegisterRequestRecipient | —
lineReleaseUserUserInfo | —
lineRemoveFromConference | —
lineRemoveProvider | —
lineSecureCall | —
lineSendUserUserInfo | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineSetAgentActivity | —
lineSetAgentGroup | Note Group names are ignored.
lineSetAgentState | —
lineSetAppSpecific | —
lineSetCallData | The memory pointed to by lpCallData is in a format specified by the application or a group of cooperating applications. The format of the data is beyond the scope of TAPI and is not converted by TAPI.
lineSetCallParams | —
lineSetCallPrivilege | —
lineSetCallQualityOfService | The format of data in the provider-specific portion of the QOS structure is beyond the scope of TAPI and is not converted by TAPI.
lineSetCallTreatment | —
lineSetCurrentLocation | —
lineSetLineDevStatus | —
lineSetMediaControl | —
lineSetMediaMode | —
lineSetNumRings | —
lineSetStatusMessages | —
lineSetTerminal | —
lineShutdown | —
lineSwapHold | —
lineUncompleteCall | —
lineUnhold | —
phoneClose | —
phoneDevSpecific | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
phoneGetData | The memory pointed to by lpData is private between the application and service provider. The application must process data in the form specified in the service provider definition.
phoneGetDisplay | The memory pointed to by lpDisplay is private between the application and service provider. The application must process data in the form specified in the service provider definition.
phoneGetGain | —
phoneGetHookSwitch | —
phoneGetLamp | —
phoneGetMessage | —
phoneGetRing | —
phoneGetStatusMessages | —
phoneGetVolume | —
phoneNegotiateAPIVersion | —
phoneNegotiateExtVersion | —
phoneOpen | —
phoneSetData | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider definition.
phoneSetDisplay | The memory pointed to by lpDisplay is private between the application and service provider. The application must provide data in the form specified in the service provider definition.
phoneSetGain | —
phoneSetHookSwitch | —
phoneSetLamp | —
phoneSetRing | —
phoneSetStatusMessages | —
phoneSetVolume | —
phoneShutdown | —
tapiRequestDrop | This function is obsolete and unavailable to Microsoft® Win32® API applications.
tapiRequestMediaCall | This function is obsolete and unavailable to Microsoft Win32 applications.


TAPI Functions

The following sections contain an alphabetic list of functions grouped by area. The information for each function includes a list of the valid call states on entry of the function and typical call state transitions when the request is complete.

Assisted Telephony Functions

Call Center Functions

Line Device Functions

Phone Device Functions

For TAPI functions categorized by service level and task, see TAPI Quick Function Reference.

Please note that service provider limitations may exist concerning the actual states in which a function can be performed. Applications must check the dwCallFeatures member in the LINECALLSTATUS structure, the dwAddressFeatures member in the LINEADDRESSSTATUS structure, and the dwLineFeatures member in the LINEDEVSTATUS structure to determine whether or not a function is permitted within the current call state.


Assisted Telephony Functions

TAPI supports the following Assisted Telephony functions:

  • tapiGetLocationInfo
  • tapiRequestDrop
  • tapiRequestMakeCall
  • tapiRequestMediaCall

For a categorization of TAPI functions by service level and task, see TAPI Quick Function Reference.


tapiGetLocationInfo

The tapiGetLocationInfo function returns the country code and city (area) code that the user has set in the current location parameters in the Telephony Control Panel. The application can use this information to assist the user in forming proper canonical telephone numbers, such as by offering these as defaults when new numbers are entered in a phone book entry or database record.

LONG WINAPI tapiGetLocationInfo(
  LPSTR lpszCountryCode,
  LPSTR lpszCityCode
);

Parameters

lpszCountryCode
A pointer to a memory location where a null-terminated string specifying the country code for the current location is to be returned. The application should allocate at least 8 bytes of storage at this location to hold the string (TAPI does not return more than 8 bytes, including the terminating NULL). An empty string (\0) is returned if the country code has not been set for the current location.
lpszCityCode
A pointer to a memory location where a null-terminated string specifying the city (area) code for the current location is to be returned. The application should allocate at least 8 bytes of storage at this location to hold the string (TAPI does not return more than 8 bytes, including the terminating NULL). An empty string (\0) is returned if the city code has not been set for the current location.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are TAPIERR_REQUESTFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Assisted Telephony Services Reference


tapiRequestDrop

The tapiRequestDrop function is nonfunctional in Win32-based applications and obsolete for all classes of Windows-based applications. It should not be used.

See Also

TAPI 2.2 Reference Overview, Assisted Telephony Services Reference


tapiRequestMakeCall

The tapiRequestMakeCall function requests the establishment of a voice call. A call-manager application is responsible for establishing the call on behalf of the requesting application, which is then controlled by the user's call-manager application.

LONG WINAPI tapiRequestMakeCall(
  LPCSTR lpszDestAddress,
  LPCSTR lpszAppName,
  LPCSTR lpszCalledParty,
  LPCSTR lpszComment
);

Parameters

lpszDestAddress
A pointer to a memory location where the null-terminated destination address of the call request is located. The address can use the canonical address format. Validity of the specified address is not checked by this operation. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator.
lpszAppName
A pointer to a memory location where the null-terminated user-friendly application name of the call request is located. This pointer can be left NULL if the application does not supply an application name. The maximum length of the address is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator. Longer strings are truncated.
lpszCalledParty
A pointer to a memory location where the null-terminated called party name for the called party of the call is located. This pointer can be left NULL if the application does not wish to supply this information. The maximum length of the string is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator. Longer strings are truncated.
lpszComment
A pointer to a memory location where the null-terminated comment about the call is located. This pointer can be left NULL if the application does not supply a comment. The maximum length of the address is TAPIMAXCOMMENTSIZE characters, which includes the NULL terminator. Longer strings are truncated.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible error return value are:

TAPIERR_NOREQUESTRECIPIENT, TAPIERR_INVALDESTADDRESS, TAPIERR_REQUESTQUEUEFULL, TAPIERR_INVALPOINTER.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall, providing only the destination address for the call. This request is forwarded to the user's call-control application, which places the call on behalf of the original application. A default call-control application is provided as part of Win32 Telephony. Users can replace this with a call-control application of their choice.

Invoking tapiRequestMakeCall when no call control application is running returns the TAPIERR_NOREQUESTRECIPIENT error indication. If the call control application is not running, TAPI attempts to launch the highest-priority call control application (which is listed for RequestMakeCall in the registry). Invoking this function when the Assisted TAPI request queue is full returns the TAPIERR_REQUESTQUEUEFULL error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Assisted Telephony Services Reference


tapiRequestMediaCall

The tapiRequestMediaCall function is nonfunctional in Win32-based applications and obsolete for all classes of Windows-based applications. It should not be used.

See Also

TAPI 2.2 Reference Overview, Assisted Telephony Services Reference


Call Center Functions

TAPI supports the following Call Center functions:

lineAgentSpecific

lineCreateAgent

lineCreateAgentSession

lineGetAgentActivityList

lineGetAgentCaps

lineGetAgentGroupList

lineGetAgentInfo

lineGetAgentSessionInfo

lineGetAgentSessionList

lineGetAgentStatus

lineGetGroupList

lineGetProxyStatus

lineGetQueueInfo

lineGetQueueList

lineProxyMessage

lineProxyResponse

lineSetAgentActivity

lineSetAgentGroup

lineSetAgentMeasurementPeriod

lineSetAgentSessionState

lineSetAgentState

lineSetAgentStateEx

lineSetQueueMeasurementPeriod


lineCreateAgent

The lineCreateAgent function creates a new Agent object. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_CREATEAGENT.

LONG lineCreateAgent(
  HLINE hLine,
  LPWSTR lpszAgentID,
  LPWSTR lpszAgentPIN,
  LPHAGENT lphAgent
);

Parameters

hLine
A handle to the line device.
lpszAgentID
A pointer to a null-terminated Unicode string containing the agent identifier. Used when working with legacy ACD systems. With an ACD system that uses the operating system's user login for authentication, lpszAgentID is set to NULL.
lpszAgentPIN
A pointer to a null-terminated Unicode string containing the agent PIN or password. Used when working with legacy ACD systems. With an ACD system that uses the operating system's user login for authentication, lpszAgentPIN is set to NULL.
lphAgent
A handle of the created agent, returned by the ACD proxy. It is the responsibility of the agent handler proxy application to generate and maintain uniqueness of this identifier.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

LINEPROXYREQUEST, LINE_PROXYREQUEST


lineAgentSpecific

The lineAgentSpecific function allows the application to access proprietary handler-specific functions of the agent handler associated with the address. The meaning of the extensions are specific to the agent handler. Each set of agent-related extensions is identified by a universally unique 128-bit extension ID that must be obtained, along with the specification for the extension, from the promulgator of that extension (usually the author of the agent handler software on the telephony server). The list of extensions supported by the agent handler is obtained from the LINEAGENTCAPS structure returned by lineGetAgentCaps.

LONG WINAPI lineAgentSpecific(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwAgentExtensionIDIndex,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwAgentExtensionIDIndex
The position in the ExtensionIDList structure in LINEAGENTCAPS of the agent handler extension being invoked.
lpParams
A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents are passed by TAPI to and from the agent handler application on the telephony server. This parameter block must specify the function to be invoked and include sufficient room for any data to be returned.
dwSize
The size, in bytes, of the parameter block area.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALAGENTID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

Additional return values are specific to the agent handler.

Remarks

This operation is part of the Extended Telephony services. It provides access to an agent handler-specific feature without defining its meaning.

This function provides a generic parameter profile. The interpretation of the parameter structure is handler specific. Indications and replies sent back to the application that are handler specific should use the LINE_AGENTSPECIFIC message.

An agent handler can provide access to handler-specific functions by defining parameters for use with this function. Applications that want to make use of these extensions should consult the vendor-specific documentation that describes what extensions are defined. Typically, an application that relies on these extensions is not able to work with other agent handler environments.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEAGENTCAPS, lineGetAgentCaps


lineCreateAgentSession

The lineCreateAgentSession function creates a new AgentSession object. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_CREATEAGENTSESSION.

LONG lineCreateAgentSession(
  HLINE hLine,
  HAGENT hAgent,
  LPWSTR lpszAgentPIN,
  DWORD dwWorkingAddressID,
  LPGUID lpGroupID,
  LPHAGENTSESSION lphAgentSession
);

Parameters

hLine
A handle to the line device.
hAgent
The identifier of the agent for whom the session is to be created.
lpszAgentPIN
A pointer to a null-terminated Unicode string containing the agent PIN or password. Used when working with legacy ACD systems that require a separate PIN for each session created (or group logged into). With an ACD system that uses the operating system's user login for authentication, lpszAgentPIN is set to NULL.
dwWorkingAddressID
The identifier of the address on which the agent will receive calls for this session.
lpGroupID
A pointer to GUID that identifies the group for which the session is being created.
lphAgentSession
A handle of the created agent session, returned by the ACD proxy. It is the responsibility of the agent handler proxy application to generate and maintain uniqueness of these identifiers.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

About TAPI 3.0 Call Center Controls, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineGetAgentActivityList

The lineGetAgentActivityList function obtains the identities of activities that the application can select using lineSetAgentActivity to indicate what function the agent is actually performing at the moment.

LONG WINAPI lineGetAgentActivityList(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTACTIVITYLIST lpAgentActivityList
);

Parameters

hLine
A handle to the open line device.
dwAddressID
The address on the open line device whose agent status is to be queried. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
lpAgentActivityList
A pointer to a variably sized structure of type LINEAGENTACTIVITYLIST. Upon successful completion of the request, this structure is filled with a list of the agent activity codes that can be selected using lineSetAgentActivity. Prior to calling lineGetAgentActivityList, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALAGENTID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEAGENTACTIVITYLIST, lineSetAgentActivity


lineGetAgentCaps

The lineGetAgentCaps function obtains the agent-related capabilities supported on the specified line device. If a specific agent is named, the capabilities include a listing of ACD groups into which the agent is permitted to log in.

LONG WINAPI lineGetAgentCaps(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAddressID,
  DWORD dwAppAPIVersion,
  LPLINEAGENTCAPS lpAgentCaps
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device containing the address to be queried.
dwAddressID
The address on the given line device whose capabilities are to be queried. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwAppAPIVersion
The highest API version supported by the application. This should not be the value negotiated using lineNegotiateAPIVersion on the device being queried.
lpAgentCaps
A pointer to a variably sized structure of type LINEAGENTCAPS. Upon successful completion of the request, this structure is filled with agent capabilities information. Prior to calling lineGetAgentCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODRIVER, LINEERR_UNINITIALIZED, LINEERR_NODEVICE.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEAGENTCAPS, lineNegotiateAPIVersion


lineGetAgentGroupList

The lineGetAgentGroupList function obtains the identities of agent groups (combination of queue, supervisor, skill level, and so on) into which the agent currently logged in on the workstation is permitted to log into on the automatic call distributor.

LONG WINAPI lineGetAgentGroupList(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTGROUPLIST lpAgentGroupList
);

Parameters

hLine
A handle to the open line device.
dwAddressID
The address on the open line device whose agent status is to be queried.
lpAgentGroupList
A pointer to a variably sized structure of type LINEAGENTGROUPLIST. Upon successful completion of the request, this structure is filled with a list of the agent groups into which the agent can log in at this time (which should include any groups into which the agent is already logged in, if any). Prior to calling lineGetAgentGroupList, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALAGENTID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEAGENTGROUPLIST


lineGetAgentInfo

The lineGetAgentInfo function returns a structure holding the ACD information associated with a particular agent handle. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_GETAGENTINFO.

LONG lineGetAgentInfo(
  HLINE hLine,
  HAGENT hAgent,
  LPLINEAGENTINFO lpAgentInfo
);

Parameters

hLine
A handle to the line device.
hAgent
The identifier of the agent whose information is to be retrieved.
lpAgentInfo
A pointer to a structure of type LINEAGENTINFO. If the request succeeds, this structure is filled with the agent statistics.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Remarks

Prior to calling the lineGetAgentInfo function, the application should set the dwTotalSize member of the LINEAGENTINFO structure to indicate the amount of memory available to TAPI for returning information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTINFO, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineGetAgentSessionInfo

The lineGetAgentSessionInfo function returns a structure that holds the ACD information associated with a particular agent session handle. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_GETAGENTSESSIONINFO.

LONG lineGetAgentSessionInfo(
  HLINE hLine,
  HAGENTSESSION hAgentSession,
  LPLINEAGENTSESSIONINFO lpAgentSessionInfo
);

Parameters

hLine
A handle to the line device.
hAgentSession
The identifier of the agent session whose information is to be retrieved.
lpAgentSessionInfo
A pointer to a structure of type LINEAGENTSESSIONINFO. Upon successful completion of the request, this structure is filled with the agent session statistics. Prior to calling the lineGetAgentSessionInfo function, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTSESSIONINFO, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineGetAgentSessionList

The lineGetAgentSessionList function returns a list of agent sessions created for the specified agent. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_GETAGENTSESSIONLIST.

LONG lineGetAgentSessionList(
  HLINE hLine,
  HAGENT hAgent,
  LPLINEAGENTSESSIONLIST lpAgentSessionList
);

Parameters

hLine
A handle to the line device.
hAgent
The identifier of the agent whose information is to be retrieved.
lpAgentSessionList
A pointer to a variably sized structure of type LINEAGENTSESSIONLIST. Upon successful completion of the request, this structure is filled with a list of the agent sessions that have been created for this agent. Prior to calling the lineGetAgentSessionList function, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTSESSIONLIST, lineGetAgentSessionList, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineGetAgentStatus

The lineGetAgentStatus function obtains the agent-related status on the specified address.

LONG WINAPI lineGetAgentStatus(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTSTATUS lpAgentStatus
);

Parameters

hLine
A handle to the open line device.
dwAddressID
The address on the open line device whose agent status is to be queried. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
lpAgentStatus
A pointer to a variably sized structure of type LINEAGENTSTATUS. Upon successful completion of the request, this structure is filled with agent status information. Prior to calling lineGetAgentStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEAGENTSTATUS


lineGetGroupList

The lineGetGroupList function returns a list of ACD groups available on the ACD system. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_GETGROUPLIST.

LONG lineGetGroupList(
  HLINE hLine,
  LPLINEAGENTGROUPLIST lpGroupList
);

Parameters

hLine
A handle to the line device.
lpGroupList
A pointer to a variably sized structure of type LINEAGENTGROUPLIST. Upon successful completion of the request, this structure is filled with a list of the available ACD groups. Prior to calling the lineGetGroupList function, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTGROUPLIST, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineGetProxyStatus

The lineGetProxyStatus function returns a list of proxy request types that are currently being serviced for the specified device.

LONG lineGetProxyStatus(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAppAPIVersion,
  LPLINEPROXYREQUESTLIST lpLineProxyRequestList
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device to be queried.
dwAppAPIVersion
The version number of TAPI to be used.
lpLineProxyRequestList
A pointer to a variably sized structure of type LINEPROXYREQUESTLIST. Upon successful completion of the request, this structure is filled with a list of the currently supported proxy requests. Prior to calling lineGetProxyStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds; otherwise, the function returns one of the following negative error values:

LINEERR_BADDEVICEID
LINEERR_INCOMPATIBLEAPIVERSION
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEPROXYREQUESTLIST


lineGetQueueInfo

The lineGetQueueInfo function returns a structure holding the ACD information associated with a particular queue. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_GETQUEUEINFO.

LONG lineGetQueueInfo(
  HLINE hLine,
  DWORD dwQueueID,
  LPLINEQUEUEINFO lpLineQueueInfo
);

Parameters

hLine
A handle to the line device.
dwQueueID
The identifier of the queue whose information is to be retrieved.
lpLineQueueInfo
A pointer to a structure of type LINEQUEUEINFO. Upon successful completion of the request, this structure is filled with the queue statistics. Prior to calling lineGetQueueInfo, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEPROXYREQUEST, LINE_PROXYREQUEST, LINEQUEUEINFO


lineGetQueueList

The lineGetQueueList function returns a list of queues associated with a particular ACD Group. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_GETQUEUELIST.

LONG lineGetQueueList(
  HLINE hLine,
  LPGUID lpGroupID,
  LPLINEQUEUELIST lpQueueList
);

Parameters

hLine
A handle to the line device.
lpGroupID
A pointer to GUID that identifies the group for which the list of queues is requested.
lpQueueList
A pointer to a variably sized structure of type LINEQUEUELIST. Upon successful completion of the request, this structure is filled with a list of queues. Prior to calling lineGetQueueList, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

About TAPI 3.0 Call Center Controls, LINE_PROXYREQUEST, LINEPROXYREQUEST, LINEQUEUELIST


lineProxyMessage

The lineProxyMessage function is used by a registered proxy request handler to generate TAPI messages related to its role. For example, an ACD agent handler can use this function to generate LINE_AGENTSTATUS messages that are received by all applications that have the specified line open. TAPI suppresses generation of the message on the hLine specified in the function parameters.

LONG WINAPI lineProxyMessage(
  HLINE hLine,
  HCALL hCall,
  DWORD dwMsg,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

hLine
A handle to the open line device. This is converted by TAPI into the correct hLine for each application that receives the message.
hCall
If the message is related to a specific call (which it is not, in the case of LINE_AGENTSTATUS), specifies the proxy handler's handle to that call; shall be set to NULL for messages not related to a specific call. This is converted by TAPI into the correct hCall for each application that receives the message.
dwMsg
The TAPI message to generate. This must be a message that is permitted to be generated by proxy handlers.
dwParam1
dwParam2
dwParam3
The parameters associated with the message to be sent.

Return Values

Returns zero if the function succeeds or one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALCALLHANDLE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_NOTREGISTERED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_AGENTSTATUS


lineProxyResponse

The lineProxyResponse function indicates completion of a proxy request by a registered proxy handler, such as an ACD agent handler on a server.

LONG WINAPI lineProxyResponse(
  HLINE hLine,
  LPLINEPROXYREQUEST lpProxyRequest,
  DWORD dwResult
);

Parameters

hLine
A handle to the open line device.
lpProxyRequest
The pointer to the proxy request buffer that was given to the application by TAPI in a LINE_PROXYREQUEST message. In the case of proxy requests that return data to the client application, the proxy handler shall have filled in the necessary structure in this buffer before calling this function. The dwNeededSize and dwUsedSize members of the structure to be returned must have been set appropriately.
dwResult
The function result that is to be returned to the calling application in a LINE_REPLY message (generated automatically by TAPI). Must be zero or one of the negative error values defined for the function invoked.

Return Values

Returns zero if the function succeeds or one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_NOTREGISTERED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions


lineSetAgentActivity

The lineSetAgentActivity function sets the agent activity code associated with a particular address.

LONG WINAPI lineSetAgentActivity(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwActivityID
);

Parameters

hLine
Handle to the line device.
dwAddressID
Identifier of the address for which the agent activity code is to be changed. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwActivityID
The new agent activity. The meaning of all values of this parameter are specific to the application and call center server.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTACTIVITY, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions


lineSetAgentGroup

The lineSetAgentGroup function sets the agent groups into which the agent is logged into on a particular address.

LONG WINAPI lineSetAgentGroup(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTGROUPLIST lpAgentGroupList
);

Parameters

hLine
Handle to the line device.
dwAddressID
Identifier of the address for which the agent information is to be changed. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
lpAgentGroupList
Pointer to a LINEAGENTGROUPLIST structure identifying the groups into which the current agent is to be logged in on the address. If the pointer is NULL or the number of groups in the indicated structure is zero, then the agent is logged out of any ACD groups into which it is currently logged in.

Note The "Name" fields in the LINEAGENTGROUPENTRY items in the list are ignored for purposes of this function; the control of the logged-in groups is based on the group identifier values only.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTGROUP, LINEERR_INVALAGENTID, LINEERR_INVALAGENTSKILL, LINEERR_INVALAGENTSUPERVISOR, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPASSWORD, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEAGENTGROUPENTRY, LINEAGENTGROUPLIST


lineSetAgentMeasurementPeriod

The lineSetAgentMeasurementPeriod function sets the measurement period associated with a particular agent. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_SETAGENTMEASUREMENTPERIOD.

LONG lineSetAgentMeasurementPeriod(
  HLINE hLine,
  HAGENT hAgent,
  DWORD dwMeasurementPeriod
);

Parameters

hLine
A handle to the line device.
hAgent
The identifier of the the agent whose information is to be changed.
dwMeasurementPeriod
The new measurement period (seconds). Must be greater than zero.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineSetAgentSessionState

The lineSetAgentSessionState function sets the agent session state associated with a particular agent session handle. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_SETAGENTSESSIONSTATE.

LONG lineSetAgentSessionState(
  HLINE hLine,
  HAGENTSESSION hAgentSession,
  DWORD dwAgentSessionState,
  DWORD dwNextAgentSessionState
);

Parameters

hLine
A handle to the line device.
hAgentSession
The identifier of the agent session whose information is to be changed.
dwAgentSessionState
The new agent session state. Must be one of the LINEAGENTSESSIONSTATE_ constants or zero to leave the agent session state unchanged and modify only the next state.
dwNextAgentSessionState
The next agent session state. Must be one of the LINEAGENTSESSIONSTATE_ constants or zero.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALAGENTSTATE
LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTSESSIONSTATE_ constants, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineSetAgentState

The lineSetAgentState function sets the agent state associated with a particular address.

LONG WINAPI lineSetAgentState(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwAgentState,
  DWORD dwNextAgentState
);

Parameters

hLine
Handle to the line device.
dwAddressID
Identifier of the address for which the agent information is to be changed. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwAgentState
The new agent state. Must be one of the LINEAGENTSTATE_ Constants, or zero to leave the agent state unchanged and modify only the next state.
dwNextAgentState
The agent state that should be automatically set when the current call on the address becomes idle. For example, if it is known that after-call work must be performed, this field can be set to LINEAGENTSTATE_WORKAFTERCALL so that a new call is not assigned to the agent after the current call. Must be one of the LINEAGENTSTATE_ Constants, or zero to use the default next state configured for the agent.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTSTATE, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions


lineSetAgentStateEx

The lineSetAgentStateEx function sets the agent state associated with a particular agent handle. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_SETAGENTSTATEEX.

LONG  lineSetAgentStateEx(
  HLINE hLine,
  HAGENT hAgent,
  DWORD dwAgentState,
  DWORD dwNextAgentState
);

Parameters

hLine
A handle to the line device.
hAgent
The identifier of the agent whose information is to be changed.
dwAgentState
The new agent state. Must be one of the LINEAGENTSTATEEX_ constants, or zero to leave the agent state unchanged and modify only the next state.
dwNextAgentState
The next agent state. Must be one of the LINEAGENTSTATEEX_ constants or zero.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALAGENTSTATE
LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEPROXYREQUEST, LINE_PROXYREQUEST


lineSetQueueMeasurementPeriod

The lineSetQueueMeasurementPeriod function sets the measurement period associated with a particular queue. It generates a LINE_PROXYREQUEST message to be sent to a registered proxy function handler, referencing a LINEPROXYREQUEST structure of type LINEPROXYREQUEST_SETQUEUEMEASUREMENTPERIOD.

LONG lineSetQueueMeasurementPeriod (
  HLINE hLine,
  DWORD dwQueueID,
  DWORD dwMeasurementPeriod
);

Parameters

hLine
A handle to the line device.
dwQueueID
The identifier of the queue whose information is to be changed.
dwMeasurementPeriod
The new measurement period (seconds). Must be greater than zero.

Return Values

Returns a request identifier if the asynchronous operation starts; otherwise, the function returns one of the following error values:

LINEERR_INVALLINEHANDLE
LINEERR_INVALPARAM
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL
LINEERR_UNINITIALIZED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

About TAPI 3.0 Call Center Controls, LINEPROXYREQUEST, LINE_PROXYREQUEST


Line Device Functions

TAPI supports the following line device functions:

  • lineAccept
  • lineAddProvider
  • lineAddToConference
  • lineAnswer
  • lineBlindTransfer
  • lineCallbackFunc
  • lineClose
  • lineCompleteCall
  • lineCompleteTransfer
  • lineConfigDialog
  • lineConfigDialogEdit
  • lineConfigProvider
  • lineDeallocateCall
  • lineDevSpecific
  • lineDevSpecificFeature
  • lineDial
  • lineDrop
  • lineForward
  • lineGatherDigits
  • lineGenerateDigits
  • lineGenerateTone
  • lineGetAddressCaps
  • lineGetAddressID
  • lineGetAddressStatus
  • lineGetAppPriority
  • lineGetCallInfo
  • lineGetCallStatus
  • lineGetConfRelatedCalls
  • lineGetCountry
  • lineGetDevCaps
  • lineGetDevConfig
  • lineGetIcon
  • lineGetID
  • lineGetLineDevStatus
  • lineGetMessage
  • lineGetNewCalls
  • lineGetNumRings
  • lineGetProviderList
  • lineGetRequest
  • lineGetStatusMessages
  • lineGetTranslateCaps
  • lineHandoff
  • lineHold
  • lineInitialize
  • lineInitializeEx
  • lineMakeCall
  • lineMonitorDigits
  • lineMonitorMedia
  • lineMonitorTones
  • lineNegotiateAPIVersion
  • lineNegotiateExtVersion
  • lineOpen
  • linePark
  • linePickup
  • linePrepareAddToConference
  • lineRedirect
  • lineRegisterRequestRecipient
  • lineReleaseUserUserInfo
  • lineRemoveFromConference
  • lineRemoveProvider
  • lineSecureCall
  • lineSendUserUserInfo
  • lineSetAppPriority
  • lineSetAppSpecific
  • lineSetCallData
  • lineSetCallParams
  • lineSetCallPrivilege
  • lineSetCallQualityOfService
  • lineSetCallTreatment
  • lineSetCurrentLocation
  • lineSetDevConfig
  • lineSetLineDevStatus
  • lineSetMediaControl
  • lineSetMediaMode
  • lineSetNumRings
  • lineSetStatusMessages
  • lineSetTerminal
  • lineSetTollList
  • lineSetupConference
  • lineSetupTransfer
  • lineShutdown
  • lineSwapHold
  • lineTranslateAddress
  • lineTranslateDialog
  • lineUncompleteCall
  • lineUnhold
  • lineUnpark

For a categorization of TAPI functions by service level and task, see TAPI Quick Function Reference.


lineAccept

The lineAccept function accepts the specified offered call. It can optionally send the specified user-user information to the calling party.

LONG WINAPI lineAccept(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call to be accepted. The application must be an owner of the call. Call state of hCall must be offering.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party as part of the call accept. This pointer can be left NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator member for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds, or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG.

Remarks

The lineAccept function is used in telephony environments like Integrated Services Digital Network (ISDN) that allow alerting associated with incoming calls to be separate from the initial offering of the call. When a call comes in, it is first offered. For some small amount of time, the application may have the option to reject the call using lineDrop, redirect the call to another station using lineRedirect, answer the call using lineAnswer, or accept the call using lineAccept. After a call has been successfully accepted by an application, alerting begins at both the called and calling device and the call state typically transitions to accepted.

Alerting is reported to the application by the LINE_LINEDEVSTATE message with the ringing indication.

The lineAccept function may also be supported by non-ISDN service providers. The call state transition to accepted can be used by other applications as an indication that another application has claimed responsibility for the call and has presented the call to the user.

The application has the option to send user-user information at the time of the accept. Even if user-user information is sent, there is no guarantee that the network will deliver this information to the calling party. An application should consult a line's device capabilities to determine whether call accept is available.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Accept overview, Supplementary Line Service Functions, LINE_REPLY, lineAnswer, LINEDEVCAPS, lineDrop, lineRedirect


lineAddProvider

The lineAddProvider function installs a new telephony service provider into the telephony system.

LONG WINAPI lineAddProvider(
  LPCSTR lpszProviderFilename,
  HWND hwndOwner,
  LPDWORD lpdwPermanentProviderID
);

Parameters

lpszProviderFilename
A pointer to a null-terminated string containing the path of the service provider to be added.
hwndOwner
A handle to a window in which any dialog boxes that need to be displayed as part of the installation process (for example, by the service provider's TSPI_providerInstall function) would be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpdwPermanentProviderID
A pointer to a DWORD-sized memory location into which TAPI writes the permanent provider identifier of the newly installed service provider.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_NOMULTIPLEINSTANCE, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED.

Remarks

During this function call, TAPI checks to ensure that it can access the service provider by calling its TSPI_providerInstall function; if this is unsuccessful (if the DLL or function cannot be found, or if TSPI_providerInstall returns an error), the function fails and the provider is not added to the telephony system. If this succeeds, and the Win32 Telephony system is active (one or more applications have called lineInitialize or lineInitializeEx), TAPI does not attempt to launch the newly-added service provider. Instead, in order to activate the new service provider, TAPI issues a message to restart Windows. When the activation succeeds, applications are informed of any new devices created by way of LINE_CREATE or PHONE_CREATE messages, or by a LINE_LINEDEVSTATE message requesting reinitialization (if the application does not support the CREATE messages).

This function copies no files—not the service provider DLL itself nor any supporting files; the application managing the addition of the provider must ensure that the provider is installed in a directory where it can be found by TAPI (for example, \WINDOWS, \WINDOWS\SYSTEM, or elsewhere on the path).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CREATE, LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx, PHONE_CREATE


lineAddToConference

The lineAddToConference function adds the call specified by hConsultCall to the conference call specified by hConfCall.

LONG WINAPI lineAddToConference(
  HCALL hConfCall,
  HCALL hConsultCall
);

Parameters

hConfCall
A handle to the conference call. The application must be an owner of this call. Any monitoring (media, tones, digits) on a conference call applies only to the hConfCall, not to the individual participating calls. Call state of hConfCall must be onHoldPendingConference or onHold.
hConsultCall
A handle to the call to be added to the conference call. The application must be an owner of this call. This call cannot be a parent of another conference or a participant in any conference. Depending on the device capabilities indicated in LINEADDRESSCAPS, the hConsultCall may not necessarily have been established using lineSetupConference or linePrepareAddToConference. The call state of hConsultCall must be connected, onHold, proceeding, or ringback. Many PBXs allow calls to be added to conferences before they are actually answered.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds, or it is a negative error number if an error occurs. Possible return values are:

LINEERR_CONFERENCEFULL, LINEERR_NOTOWNER, LINEERR_INVALCONFCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

If LINEERR_INVALCALLHANDLE is returned, the specified call handle for the added call is invalid; hConsultCall is a parent of another conference or already a participant in a conference; hConsultCall cannot be added for other reasons (such as, it must have been established using lineSetupConference or linePrepareAddToConference); or hConsultCall and hConfCall are calls on different open lines.

The call handle of the added party remains valid after adding the call to a conference. Its state typically changes to conferenced while the state of the conference call typically becomes connected. Using lineGetConfRelatedCalls, you can obtain a list of call handles that are part of the same conference call as the specified call. The specified call is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls. The handle to an individual participating call can be used later to remove that party from the conference call using lineRemoveFromConference.

If lineGetConfRelatedCalls is called immediately after lineAddToConference, it may not return a complete list of related calls because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference (that is, the conferenced state is confirmed by the service provider). After the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

Note All calls that are part of a conference must exist on the same open line.

The call states of the calls participating in a conference are not independent. For example, when dropping a conference call, all participating calls can automatically become idle. An application should consult the line's device capabilities to determine what form of conference removal is available. The application should track the LINE_CALLSTATE messages to determine what happened to the calls involved.

The conference call is established either by lineSetupConference or lineCompleteTransfer. The call added to a conference is typically established using lineSetupConference or linePrepareAddToConference. Some switches can allow adding arbitrary calls to the conference, and such a call can have been set up using lineMakeCall and be on (hard) hold. The application can examine the dwAddrCapFlags member of the LINEADDRESSCAPS structure to determine the permitted operations.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Conference overview, Supplementary Line Service Functions, LINE_CALLSTATE, LINEADDRESSCAPS, lineCompleteTransfer, lineGetConfRelatedCalls, lineMakeCall, linePrepareAddToConference, lineRemoveFromConference, lineSetupConference


lineAnswer

The lineAnswer function answers the specified offering call.

LONG WINAPI lineAnswer(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call to be answered. The application must be an owner of this call. The call state of hCall must be offering or accepted.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party at the time the call is answered. This pointer can be left NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_NOTOWNER.

Remarks

When a new call arrives, applications with an interest in the call are sent a LINE_CALLSTATE message to provide the new call handle and to inform the application about the call's state and the privileges to the new call (such as monitor or owner). The application with owner privilege for the call can answer this call using lineAnswer. After the call has been successfully answered, the call typically transitions to the connected state. Initially, only one application is given owner privilege to the incoming call.

In some telephony environments (like ISDN), where user alerting is separate from call offering, the application can have the option to accept a call prior to answering or to reject or redirect the offering call.

If a call comes in (is offered) at the time another call is already active, invoking lineAnswer connects to the new call. The effect this has on the existing active call depends on the line's device capabilities. The first call can be unaffected, it can automatically be dropped, or it can automatically be placed on hold. The appropriate LINE_CALLSTATE messages report state transitions to the application about both calls.

In a bridged situation, if a call is connected but in the LINECONNECTEDMODE_INACTIVE state, it can be joined using the lineAnswer function.

The application has the option to send user-user information at the time of the answer. Even if user-user information can be sent, there is no guarantee that the network will deliver this information to the calling party. An application should consult a line's device capabilities to determine whether sending user-user information upon answering the call is available.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_REPLY, LINEDEVCAPS


lineBlindTransfer

The lineBlindTransfer function performs a blind or single-step transfer of the specified call to the specified destination address.

LONG WINAPI lineBlindTransfer(
  HCALL hCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

hCall
A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be connected.
lpszDestAddress
A pointer to a null-terminated string identifying where the call is to be transferred to. The destination address uses the standard dialable number format.
dwCountryCode
The country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of 0 is specified, a default call-progress protocol defined by the service provider is used.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCOUNTRYCODE, LINEERR_INVALCALLSTATE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESS, LINEERR_UNINITIALIZED, LINEERR_ADDRESSBLOCKED, LINEERR_OPERATIONFAILED.

Remarks

If LINEERR_INVALADDRESS is returned, no dialing occurs.

Blind transfer differs from a consultation transfer in that no consultation call is made visible to the application. After the blind transfer successfully completes, the specified call is typically cleared from the application's line, and it transitions to the idle state.

The application's call handle remains valid after the transfer has completed. The application must deallocate its handle using lineDeallocateCall when it is no longer interested in the transferred call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Transfer overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY, lineDeallocateCall


lineCallbackFunc

The lineCallbackFunc function is a placeholder for the application-supplied function name.

VOID FAR PASCAL lineCallbackFunc(
  DWORD hDevice,
  DWORD dwMsg,
  DWORD dwCallbackInstance,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

hDevice
A handle to either a line device or a call associated with the callback. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMsg. Applications must use the DWORD type for this parameter because using the HANDLE type may generate an error.
dwMsg
A line or call device message.
dwCallbackInstance
Callback instance data passed back to the application in the callback. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For information about parameter values passed to this function, see Line Device Messages.

All callbacks occur in the application's context. The callback function must reside in a DLL or application module.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.


lineClose

The lineClose function closes the specified open line device.

LONG WINAPI lineClose(
  HLINE hLine
);

Parameters

hLine
A handle to the open line device to be closed. After the line has been successfully closed, this handle is no longer valid.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

If an application calls lineClose while it still has active calls on the opened line, the application's ownership of these calls is revoked. If the application was the sole owner of these calls, the calls are dropped as well. It is good programming practice for an application to dispose of the calls it owns on an opened line by explicitly relinquishing ownership and/or by dropping these calls prior to closing the line.

If the line was closed successfully, a LINE_LINEDEVSTATE message is sent to all applications that are monitoring the line status of open/close changes. Outstanding asynchronous replies are suppressed.

Service providers may find it useful or necessary to forcibly reclaim line devices from an application that has the line open. This can be useful to prevent an application from monopolizing the line device for too long. If this happens, a LINE_CLOSE message is sent to the application, specifying the line handle of the line device that was closed.

The lineOpen function allocates resources to the invoking application, and applications can be prevented from opening a line if resources are unavailable. Therefore, an application that only occasionally uses a line device (such as for making outgoing calls) should close the line to free resources and allow other applications to open the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CLOSE, LINE_LINEDEVSTATE, lineOpen


lineCompleteCall

The lineCompleteCall function specifies how a call that could not be connected normally should be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer. The application can request that the call be completed in one of a number of ways.

LONG WINAPI lineCompleteCall(
  HCALL hCall,
  LPDWORD lpdwCompletionID,
  DWORD dwCompletionMode,
  DWORD dwMessageID
);

Parameters

hCall
A handle to the call whose completion is requested. The application must be an owner of the call. The call state of hCall must be busy, ringback.
lpdwCompletionID
A pointer to a DWORD-sized memory location. The completion identifier is used to identify individual completion requests in progress. A completion identifier becomes invalid and can be reused after the request completes or after an outstanding request is canceled.
dwCompletionMode
The way in which the call is to be completed. This parameter uses one and only one of the LINECALLCOMPLMODE_ Constants.
dwMessageID
The message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This identifier selects the message from a small number of predefined messages.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_COMPLETIONOVERRUN, LINEERR_NOMEM, LINEERR_INVALCALLCOMPLMODE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMESSAGEID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

This function is considered complete when the request has been accepted by the network or switch; not when the request is fully completed in the way specified. After this function completes, the call typically transitions to idle. When the called station or network enters a state where the call can be completed as requested, the application is notified by a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record lists the reason for the call as CALLCOMPLETION and provides the completion identifier as well. It is possible to have multiple outstanding call completion requests; the maximum number is device dependent. The completion identifier is also used to refer to each individual request so requests can be canceled by calling lineUncompleteCall.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CALLSTATE, LINE_REPLY, LINECALLINFO, lineUncompleteCall


lineCompleteTransfer

The lineCompleteTransfer function completes the transfer of the specified call to the party connected in the consultation call.

LONG WINAPI lineCompleteTransfer(
  HCALL hCall,
  HCALL hConsultCall,
  LPHCALL lphConfCall,
  DWORD dwTransferMode
);

Parameters

hCall
A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer.
hConsultCall
A handle to the call that represents a connection with the destination of the transfer. The application must be an owner of this call. The call state of hConsultCall must be connected, ringback, busy, or proceeding.
lphConfCall
A pointer to a memory location where an hCall handle can be returned. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the newly created conference call is returned in lphConfCall and the application becomes the sole owner of the conference call. Otherwise, this parameter is ignored by TAPI.
dwTransferMode
Specifies how the initiated transfer request is to be resolved. This parameter uses one of the LINETRANSFERMODE_ Constants.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCONSULTCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALTRANSFERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The LINE_REPLY message sent in response to a call to the lineCompleteTransfer function is based on the status of the call specified by the hCall parameter.

This operation completes the transfer of the original call, hCall, to the party currently connected by hConsultCall. The consultation call is typically dialed on the consultation call allocated as part of lineSetupTransfer, but it can be any call to which the switch is capable of transferring hCall.

The transfer request can be resolved either as a transfer or as a three-way conference call. When resolved as a transfer, the parties connected by hCall and hConsultCall are connected to each other, and both hCall and hConsultCall are typically cleared from the application's line and transition to the idle state. The application's call handle remains valid after the transfer has completed. The application must deallocate its handle with lineDeallocateCall when it is no longer interested in the transferred call.

When resolved as a conference, all three parties enter into a conference call. Both existing call handles remain valid but transition to the conferenced state. A conference call handle is created and returned, and it transitions to the connected state.

If lineGetConfRelatedCalls is called immediately after lineCompleteTransfer with the result that the calls are conferenced, lineGetConfRelatedCalls may not return a complete list of related calls. This is because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference. That is, it waits for the service provider to confirm the conferenced state. After the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

It can also be possible to perform a blind transfer of a call using lineBlindTransfer.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Transfer overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CALLSTATE, LINE_REPLY, lineBlindTransfer, lineDeallocateCall, lineGetConfRelatedCalls, lineSetupTransfer


lineConfigDialog

The lineConfigDialog function causes the provider of the specified line device to display a dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line device.

LONG WINAPI lineConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpszDeviceClass
A pointer to a null-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

The lineConfigDialog function causes the service provider to display a modal dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line specified by dwDeviceID. The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter would be "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineGetID


lineConfigDialogEdit

The lineConfigDialogEdit function causes the provider of the specified line device to display a dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line device.

LONG WINAPI lineConfigDialogEdit(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCSTR lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD dwSize,
  LPVARSTRING lpDeviceConfigOut
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpszDeviceClass
A pointer to a null-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.
lpDeviceConfigIn
A pointer to the opaque configuration data structure that was returned by lineGetDevConfig (or a previous invocation of lineConfigDialogEdit) in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfigIn. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig or a previous invocation of lineConfigDialogEdit.
lpDeviceConfigOut
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig (or a future invocation of lineConfigDialogEdit), the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

If LINEERR_STRUCTURETOOSMALL is returned, the dwTotalSize member of the VARSTRING structure pointed to by lpDeviceConfigOut does not specify enough memory to contain the entire configuration structure. The dwNeededSize member has been set to the amount required. To the extent that user entries were reflected in information that could not be returned due to insufficient space, those edits are lost; applications should therefore allocate the maximum amount of space that may be needed by the device class to return its configuration structure (for more information, see TAPI Device Classes).

The lineConfigDialogEdit function causes the service provider to display a modal dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line specified by dwDeviceID.

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter would be "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

The difference between this function and lineConfigDialog is the source of the parameters to edit and the result of the editing. In lineConfigDialog, the parameters edited are those currently in use on the device (or set for use on the next call), and any changes made have (to the maximum extent possible) an immediate impact on any active connection; also, the application must use lineGetDevConfig to fetch the result of parameter changes from lineConfigDialog. With lineConfigDialogEdit, the parameters to edit are passed in from the application, and the results are returned to the application, with no impact on active connections; the results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. However, the output of this function can be passed to lineSetDevConfig to affect the current call or next call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineConfigDialog, lineGetDevConfig, lineGetID, lineSetDevConfig, VARSTRING


lineConfigProvider

The lineConfigProvider function causes a service provider to display its configuration dialog box.

LONG WINAPI lineConfigProvider(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
A handle to a window to which the configuration dialog box (displayed by TSPI_providerConfig) is attached. Can be NULL to indicate that any window created during the function should have no owner window.
dwPermanentProviderID
The permanent provider identifier of the service provider to be configured.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

Remarks

This is basically a straight pass-through to TSPI_providerConfig.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions


lineDeallocateCall

The lineDeallocateCall function deallocates the specified call handle.

LONG WINAPI lineDeallocateCall(
  HCALL hCall
);

Parameters

hCall
The call handle to be deallocated. An application with monitoring privileges for a call can always deallocate its handle for that call. An application with owner privilege for a call can deallocate its handle unless it is the sole owner of the call and the call is not in the idle state. The call handle is no longer valid after it has been deallocated.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The deallocation does not affect the call state of the physical call. It does, however, release internal resources related to the call.

In API versions earlier than 2.0, if the application is the sole owner of a call and the call is not in the idle state, LINEERR_INVALCALLSTATE is returned. In this case, the application can first drop the call using lineDrop and deallocate its call handle afterwards. An application that has monitor privilege for a call can always deallocate its handle for the call.

In API versions 2.0 or later, the sole owner of the call can deallocate its handle even though the call is not in the idle state. (This allows for distributed control of the call in a client/server environment.)

Note Be aware that leaving the call without an owner can result in the user being unable to terminate the call if there are monitoring applications open preventing TAPI from calling TSPI_lineCloseCall. Use this feature only if the application can determine that the call can be controlled externally by the user (see LINEADDRCAPFLAGS_CLOSEDROP).

In API versions earlier than 2.0, when the lineDeallocateCall function deallocates a call handle, it also suspends further processing of any outstanding LINE_REPLY messages for the call. An application must be designed not to wait indefinitely for LINE_REPLY messages for each corresponding call to an asynchronous function if it also uses the lineDeallocateCall function to deallocate handles.

In API versions 2.0 or later, lineDeallocateCall does not suspend outstanding LINE_REPLY messages; every asynchronous function that returns a dwRequestID to the application always results in the delivery of the associated LINE_REPLY message unless the application calls lineShutdown.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Terminate a Session Overview, TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_REPLY, lineDrop, lineShutdown


lineDevSpecific

The lineDevSpecific function enables service providers to provide access to features not offered by other TAPI functions. The meaning of the extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.

LONG WINAPI lineDevSpecific(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hLine
A handle to a line device. This parameter is required.
dwAddressID
An address identifier on the given line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
hCall
A handle to a call. This parameter is optional, but if it is specified, the call it represents must belong to the hLine line device. The call state of hCall is device specific.
lpParams
A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents are passed by TAPI to or from the service provider.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds, or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Additional return values are device specific.

Remarks

This operation is part of the Extended Telephony services. It provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

This function provides a generic parameter profile. The interpretation of the parameter structure is device specific. Whether dwAddressID and/or hCall are expected to be valid is device specific. If specified, they must belong to hLine. Indications and replies sent back the application that are device specific should use the LINE_DEVSPECIFIC message.

A service provider can provide access to device-specific functions by defining parameters for use with this function. Applications that want to make use of these device-specific extensions should consult the device-specific (in this case, vendor-specific) documentation that describes what extensions are defined. Typically, an application that relies on these device-specific extensions is not able to work with other service provider environments.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Extended Telephony Services Reference, LINE_DEVSPECIFIC, LINE_REPLY


lineDevSpecificFeature

The lineDevSpecificFeature function enables service providers to provide access to features not offered by other TAPI functions. The meaning of these extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.

LONG WINAPI lineDevSpecificFeature(
  HLINE hLine,
  DWORD dwFeature,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hLine
A handle to the line device.
dwFeature
The feature to invoke on the line device. This parameter uses the PHONEBUTTONFUNCTION_ Constants.
lpParams
A pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific and its contents are passed through by TAPI to or from the service provider.
dwSize
The size of the buffer in bytes.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALFEATURE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Additional return values are device specific.

Remarks

This operation is part of the Extended Telephony services. It provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

This function provides the application with phone feature-button emulation capabilities. When an application invokes this operation, it specifies the equivalent of a button-press event. This method of invoking features is device dependent, as TAPI does not define their meaning. Typically, an application that relies on these device-specific extensions does not work with other service provider environments.

The structure pointed to by lpParams should not contain any pointers because they would not be properly translated (thunked) when running a 16-bit application in a 32-bit version of TAPI and vice versa.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Extended Telephony Services Reference, LINE_REPLY


lineDial

The lineDial function dials the specified dialable number on the specified call.

LONG WINAPI lineDial(
  HCALL hCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

hCall
A handle to the call on which a number is to be dialed. The application must be an owner of the call. The call state of hCall can be any state except idle and disconnected.
lpszDestAddress
The destination to be dialed using the standard dialable number format.
dwCountryCode
The country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of 0 is specified, a service provider-defined default call progress protocol is used.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALPOINTER, LINEERR_DIALBILLING, LINEERR_NOMEM, LINEERR_DIALDIALTONE, LINEERR_NOTOWNER, LINEERR_DIALPROMPT, LINEERR_OPERATIONFAILED, LINEERR_DIALQUIET, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE.

Remarks

If LINEERR_INVALADDRESS is returned, no dialing has been done. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineDial have occurred. For example, none of the dialable addresses prior to the offending character has been dialed, no hookswitch state has changed, and so on.

The lineDial function is used for dialing on an existing call appearance. For example, after a call has been set up for transfer or conference, a consultation call is automatically allocated, and the lineDial function would be used to perform the dialing of this consultation call. The lineDial function can be invoked multiple times in the course of multistage dialing, if the line's device capabilities allow it. Also, multiple addresses can be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses and can return a single call handle to the aggregate of all calls to the application. All addresses would use the same country code.

Dialing is considered complete after the address has been passed to the service provider; not after the call is finally connected. Service providers that provide inverse multiplexing can allow multiple addresses to be provided at once. The service provider sends LINE_CALLSTATE messages to the application to inform it about the progress of the call. To abort a call attempt while a call is being established, the invoking application should use lineDrop.

An application can set the lpszDestAddress parameter of the lineDial function to the address of an empty string to indicate that dialing is complete, but only if the previous calls to the lineMakeCall and lineDial functions have had the strings specified by lpszDestAddress terminated with semicolons.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Dial Overview, TAPI 2.2 Reference Overview, Basic Telephony Services Reference, Dialable Addresses, LINE_CALLSTATE, LINE_REPLY, lineDrop, lineMakeCall


lineDrop

The lineDrop function drops or disconnects the specified call. The application has the option to specify user-user information to be transmitted as part of the call disconnect.

LONG WINAPI lineDrop(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call to be dropped. The application must be an owner of the call. The call state of hCall can be any state except idle.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED.

Remarks

When invoking lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call can drop all individual participating calls. LINE_CALLSTATE messages are sent to the application for all calls whose call state is affected. A dropped call typically transitions to the idle state. Invoking lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

A call in the onholdpending state typically reverts to the connected state. When dropping the consultation call to the third party for a conference call or when removing the third party in a previously established conference call, the provider (and switch) can release the conference bridge and revert the call back to a normal two-party call. If this is the case, hConfCall transitions to the idle state, and the only remaining participating call transitions to the connected state. Some switches automatically "unhold" the other call.

The application has the option to send user-user information at the time of the drop. Even if user-user information can be sent, there is no guarantee that the network will deliver this information to the remote party.

In various bridged or party-line configurations when multiple parties are on the call, lineDrop may not actually clear the call. For example, in a bridged situation, a lineDrop operation may not actually drop the call because the status of other stations on the call may govern; instead, the call may simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Drop overview, Terminate a Session overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions


lineForward

The lineForward function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. This function provides a combination of forward and do-not-disturb features. This function can also cancel forwarding currently in effect.

LONG WINAPI lineForward(
  HLINE hLine,
  DWORD bAllAddresses,
  DWORD dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD dwNumRingsNoAnswer,
  LPHCALL lphConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hLine
A handle to the line device.
bAllAddresses
Specifies whether all originating addresses on the line or just the one specified is to be forwarded. If TRUE, all addresses on the line are forwarded and dwAddressID is ignored; if FALSE, only the address specified as dwAddressID is forwarded.
dwAddressID
The address on the specified line whose incoming calls are to be forwarded. This parameter is ignored if bAllAddresses is TRUE.

An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

lpForwardList
A pointer to a variably sized data structure that describes the specific forwarding instructions, of type LINEFORWARDLIST.
dwNumRingsNoAnswer
The number of rings before a call is considered a "no answer." If dwNumRingsNoAnswer is out of range, the actual value is set to the nearest value in the allowable range.
lphConsultCall
A pointer to an HCALL location. In some telephony environments, this location is loaded with a handle to a consultation call that is used to consult the party that is being forwarded to, and the application becomes the initial sole owner of this call. This pointer must be valid even in environments where call forwarding does not require a consultation call. This handle is set to NULL if no consultation call is created.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. This pointer is ignored unless lineForward requires the establishment of a call to the forwarding destination (and lphConsultCall is returned, in which case lpCallParams is optional). If NULL, default call parameters are used. Otherwise, the specified call parameters are used for establishing hConsultCall.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.

Remarks

A successful forwarding indicates only that the request has been accepted by the service provider, not that forwarding is set up at the switch. A LINE_ADDRESSSTATE (forwarding) message provides confirmation for forwarding having been set up at the switch.

Forwarding of the address(es) remains in effect until this function is called again. The most recent forwarding list replaces the old one. Forwarding can be canceled by specifying a NULL pointer as lpForwardList. If a NULL destination address is specified for an entry in the forwarding list, the operation acts as a do-not-disturb.

Forwarding status of an address can also be affected externally; for example, by administrative actions at the switch or by a user from another station. It may not be possible for the service provider to be aware of this state change, and it may not be able to keep in synchronization with the forwarding state known to the switch.

Because a service provider may not know the forwarding state of the address "for sure" (that is, it may have been forwarded or unforwarded in an unknown way), lineForward succeeds unless it fails to set the new forwarding instructions. In other words, a request that all forwarding be canceled at a time that there is no forwarding in effect is successful. This is because there is no "unforwarding"—you can only change the previous set of forwarding instructions.

The success or failure of this operation does not depend on the previous set of forwarding instructions, and the same is true when setting different forwarding instructions. The provider should "unforward everything" prior to setting the new forwarding instructions. Because this can take time in analog telephony environments, a provider may also want to compare the current forwarding with the new one, and only issue instructions to the switch to get to the final state (leaving unchanged forwarding unaffected).

Invoking lineForward when LINEFORWARDLIST has dwNumEntries set to zero has the same effect as providing a NULL lpForwardList parameter. It cancels all forwarding currently in effect.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Forward Overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_ADDRESSSTATE, LINE_REPLY, LINECALLPARAMS, LINEFORWARDLIST


lineGatherDigits

The lineGatherDigits function initiates the buffered gathering of digits on the specified call. The application specifies a buffer in which to place the digits and the maximum number of digits to be collected.

LONG WINAPI lineGatherDigits(
  HCALL hCall,
  DWORD dwDigitModes,
  LPSTR lpsDigits,
  DWORD dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD dwFirstDigitTimeout,
  DWORD dwInterDigitTimeout
);

Parameters

hCall
A handle to the call on which digits are to be gathered. The application must be an owner of the call. The call state of hCall can be any state.
dwDigitModes
The digit mode(s) to be monitored. This parameter uses one or more of the LINEDIGITMODE_ Constants.
lpsDigits
A pointer to the buffer where detected digits are to be stored as text characters. Digits may not show up in the buffer one at a time as they are collected. Only after a LINE_GATHERDIGITS message is received should the content of the buffer be assumed to be valid. If lpsDigits is NULL, the digit gathering currently in progress on the call is terminated and dwNumDigits is ignored. Otherwise, lpsDigits is assumed to have room for dwNumDigits digits.
dwNumDigits
The number of digits to be collected before a LINE_GATHERDIGITS message is sent to the application. The dwNumDigits parameter is ignored when lpsDigits is NULL. This function fails if dwNumDigits is zero.
lpszTerminationDigits
Specifies a null-terminated string of termination digits as text characters. If one of the digits in the string is detected, that termination digit is appended to the buffer, digit collection is terminated, and the LINE_GATHERDIGITS message is sent to the application.

The list of valid characters is dependent on the constant provided in dwDigitModes. For a list of the valid characters for each possible mode, see LINEDIGITMODE_ Constants.

If this pointer is NULL, or if it points to an empty string, the function behaves as though no termination digits were supplied.

dwFirstDigitTimeout
The time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the NULL character, indicating that no digits were received and the first digit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported.
dwInterDigitTimeout
The maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the digits collected up to this point followed by a NULL character, indicating that an interdigit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

Digit collection is terminated when the requested number of digits has been collected. It is also terminated when one of the digits detected matches a digit in szTerminationDigits before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned.

Another way of canceling digit collection occurs when one of the timeouts expires. The dwFirstDigitTimeout expires if the first digit is not received in this time period. The dwInterDigitTimout expires if the second, third, (and so forth) digit is not received within that time period from the previously detected digit, and a partial buffer is returned.

A fourth method for terminating digit collection is by calling this function again while collection is in progress. The old collection session is terminated, any digits collected up to that point are copied to the buffer supplied from the previous call to this function, and the buffer is delivered when the LINE_GATHERDIGITS message is sent to the application. The mechanism for terminating digit gathering without initiating another gathering of the digits is to invoke this function with lpsDigits equal to NULL.

This function is considered successful if digit collection has been correctly initiated, not if digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by a NULL character.

Although this function can be invoked in any call state, digits can typically only be gathered while the call is in the connected state.

The message LINE_GATHERDIGITS is sent only to the application that initiated the request. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled by another lineGatherDigits request on the call. Only one gather-digits request can be active on a call at any given time across all applications that are owners of the call. Given the asynchronous behavior of the operation, an application that issues multiple lineGatherDigits requests in quick succession may be able to do so and receive several LINE_GATHERDIGITS messages later. While this would be unusual application behavior, the application is able to count the number of these messages to allow cancel messages to be matched with the earlier requests. In any case, only the most recent request should be assumed to be valid.

Note When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a LINE_REPLY or LINE_GATHERDIGITS message is received.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a LINE_MONITORDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be simutaneously enabled for the same call.

Gathering of digits on a conference call applies only to the hConfCall, not to the individual participating calls.

If the lineGatherDigits function is used to cancel a previous request to gather digits, the function copies any digits collected up to that point to the buffer specified in the original function call. The function then sends a LINE_GATHERDIGITS message to the application, regardless of whether the lpszDigits parameter in the second call specifies a NULL or different address.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_GATHERDIGITS, LINE_REPLY, LINE_MONITORDIGITS, lineMonitorDigits


lineGenerateDigits

The lineGenerateDigits function initiates the generation of the specified digits on the specified call as inband tones using the specified signaling mode. Invoking this function with a NULL value for lpszDigits aborts any digit generation currently in progress. Invoking lineGenerateDigits or lineGenerateTone while digit generation is in progress aborts the current digit generation or tone generation and initiates the generation of the most recently specified digits or tone.

LONG WINAPI lineGenerateDigits(
  HCALL hCall,
  DWORD dwDigitMode,
  LPCSTR lpszDigits,
  DWORD dwDuration
);

Parameters

hCall
A handle to the call. The application must be an owner of the call. Call state of hCall can be any state.
dwDigitMode
The format to be used for signaling these digits. Note that dwDigitMode is allowed to have only a single flag set. This parameter uses one of the LINEDIGITMODE_ Constants.
lpszDigits
A pointer to a null-terminated character buffer that contains the digits to be generated. Valid characters are those specified for the LINEDIGITMODE_ Constants provided in dwDigitModes.

In addition, ',' (comma) is also a valid character. A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined, and the line's device capabilities indicate what this duration is. Multiple commas can be used to inject longer pauses. Invalid digits are ignored during the generation, rather than being reported as errors.

'!' (exclamation) is a valid character. This character causes a "hookflash" operation, as described for dialable addresses.

dwDuration
Both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of 0 uses a default value. The dwDuration parameter must be within the range specified by MinDialParams and MaxDialParams in LINEDEVCAPS. If out of range, the actual value is set to the nearest value in the range.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The lineGenerateDigits function is considered to have completed successfully when the digit generation has been successfully initiated, not when all digits have been generated. In contrast to lineDial, which dials digits in a network-dependent fashion, lineGenerateDigits guarantees to produce the digits as inband tones over the voice channel using DTMF or hookswitch dial pulses when using pulse. The lineGenerateDigits function is generally not suitable for making calls or dialing. It is intended for end-to-end signaling over an established call.

After all digits in lpszDigits have been generated, or after digit generation has been aborted or canceled, a LINE_GENERATE message is sent to the application.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all applications that are owners of the call. Digit generation on a call is canceled by initiating either another digit generation request or a tone generation request. To cancel the current digit generation, the application can invoke lineGenerateDigits and specify NULL for the lpszDigits parameter.

Depending on the service provider and hardware, the application can monitor the digits it generates itself. If that is not desired, the application can disable digit monitoring while generating digits.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_GENERATE, LINEDEVCAPS, lineDial, lineGenerateTone


lineGenerateTone

The lineGenerateTone function generates the specified inband tone over the specified call. Invoking this function with a zero for dwToneMode aborts the tone generation currently in progress on the specified call. Invoking lineGenerateTone or lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation and initiates the generation of the newly specified tone or digits.

LONG WINAPI lineGenerateTone(
  HCALL hCall,
  DWORD dwToneMode,
  DWORD dwDuration,
  DWORD dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameters

hCall
A handle to the call on which a tone is to be generated. The application must be an owner of the call. The call state of hCall can be any state.
dwToneMode
Defines the tone to be generated. Tones can be either standard or custom. A custom tone is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified with dwDuration for both standard and custom tones. The dwToneMode parameter can only have one bit set. If no bits are set (the value 0 is passed), tone generation is canceled. This parameter uses one of the LINETONEMODE_ Constants.
dwDuration
Duration in milliseconds during which the tone should be sustained. A value of 0 for dwDuration uses a default duration for the specified tone. Default values are:

CUSTOM: The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.

RINGBACK: The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.

BUSY: The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.

BEEP: The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.

BILLING: Fixed (single cycle).

dwNumTones
The number of entries in the lpTones array. This parameter is ignored if dwToneMode is not equal to CUSTOM.
lpTones
A pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter is ignored for standard LINETONEMODE_ Constants tones such as LINETONEMODE_BUSY. If lpTones is a multifrequency tone, the various tones are played simultaneously.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGenerateTone function is considered to have completed successfully when the tone generation has been successfully initiated, not when the generation of the tone is finished. The function allows the inband generation of several predefined tones, such as ringback, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence, and volume. Because these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When the generation of the tone is complete, or when tone generation is canceled, a LINE_GENERATE message is sent to the application.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all applications that are owners of the call. This implies that if tone generation is currently in progress on a call, invoking lineGenerateDigits cancels the tone generation.

If the LINEERR_INVALPOINTER error value is returned, the specified lpTones parameter is invalid or the value specified by the dwNumTones parameter is too large.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_GENERATE, lineGenerateDigits, LINEGENERATETONE


lineGetAddressCaps

The lineGetAddressCaps function queries the specified address on the specified line device to determine its telephony capabilities.

LONG WINAPI lineGetAddressCaps(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAddressID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  LPLINEADDRESSCAPS lpAddressCaps
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device containing the address to be queried.
dwAddressID
The address on the given line device whose capabilities are to be queried. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwAPIVersion
The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained by lineNegotiateAPIVersion.
dwExtVersion
The version number of the service provider-specific extensions to be used. This number can be set to zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; and the low-order word contains the minor version number.
lpAddressCaps
A pointer to a variably sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure is filled with address capabilities information. Prior to calling lineGetAddressCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALAPPHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODRIVER, LINEERR_NODEVICE.

Remarks

Valid address identifiers range from zero to one less than the number of addresses returned by lineGetDevCaps. The version number to be supplied is the version number that was returned as part of the line's device capabilities by lineGetDevCaps.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINEADDRESSCAPS, lineGetDevCaps, lineNegotiateAPIVersion


lineGetAddressID

The lineGetAddressID function returns the address identifier associated with an address in a different format on the specified line.

LONG WINAPI lineGetAddressID(
  HLINE hLine,
  LPDWORD lpdwAddressID,
  DWORD dwAddressMode,
  LPCSTR lpsAddress,
  DWORD dwSize
);

Parameters

hLine
A handle to the open line device.
lpdwAddressID
A pointer to a DWORD-sized memory location where the address identifier is returned. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwAddressMode
The address mode of the address contained in lpsAddress. This parameter uses one and only one of the LINEADDRESSMODE_ Constants. You must specify LINEADDRESSMODE_DIALABLEADDR.
lpsAddress
A pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by dwAddressMode. Because the only valid value is LINEADDRESSMODE_DIALABLEADDR, lpsAddress uses the common dialable number format and is null-terminated.
dwSize
The size of the address contained in lpsAddress.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESS, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGetAddressID function is used to map a phone number (address) assigned to a line device back to its dwAddressID in the range zero to the number of addresses minus one returned in the line's device capabilities. The lineMakeCall function allows the application to make a call by specifying a line handle and an address on the line. The address can be specified as a dwAddressID, as a phone number, or as a device-specific name or identifier. Using a phone number can be practical in environments where a single line is assigned multiple addresses.

Note LINEADDRESSMODE_ADDRESSID may not be used with lineGetAddressID.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineMakeCall


lineGetAddressStatus

The lineGetAddressStatus function allows an application to query the specified address for its current status.

LONG WINAPI lineGetAddressStatus(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEADDRESSSTATUS lpAddressStatus
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the given open line device. This is the address to be queried. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
lpAddressStatus
A pointer to a variably sized data structure of type LINEADDRESSSTATUS. Prior to calling lineGetAddressStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINEADDRESSSTATUS


lineGetAppPriority

The lineGetAppPriority function allows an application to determine whether or not it is in the handoff priority list for a particular media mode or Assisted Telephony request mode and, if so, its position in the priority list.

LONG WINAPI lineGetAppPriority(
  LPCSTR lpszAppFilename,
  DWORD dwMediaMode,
  LPLINEEXTENSIONID lpExtensionID,
  DWORD dwRequestMode,
  LPVARSTRING lpExtensionName,
  LPDWORD lpdwPriority
);

Parameters

lpszAppFilename
A pointer to a string containing the application executable module file name (without directory information). In API version 2.0 or later, the parameter can be in long file name format, of which the 8.3 file name format is a proper subset. Long file names, unlike 8.3 file names, are case preserving. Neither file name format is case sensitive. See File Name Conventions. In API versions earlier than 2.0, the parameter must specify a file name in the 8.3 format; long file names cannot be used.
dwMediaMode
The media mode for which the priority information is to be obtained. The value can be one of the LINEMEDIAMODE_ Constants; only a single bit can be on. The value 0 should be used if checking application priority for Assisted Telephony requests.
lpExtensionID
A pointer to structure of type LINEEXTENSIONID. This parameter is ignored.
dwRequestMode
If the dwMediaMode parameter is zero, this parameter specifies the Assisted Telephony request mode for which priority is to be checked. It must be either LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL. This parameter is ignored if dwMediaMode is non-zero.
lpExtensionName
This parameter is ignored.
lpdwPriority
A pointer to a DWORD-size memory location into which TAPI writes the priority of the application for the specified media or request mode. The value 0 is returned if the application is not in the stored priority list and does not currently have any line device open with ownership requested of the specified media mode or having registered for the specified request mode.

In API versions earlier than 2.0, the value –1 (0xFFFFFFFF) is returned if the application has the line open for the specified media mode or has registered for the specified requests, but the application is not in the stored priority list (that is, it is in the temporary priority list only). In API version 2.0 or later, the value 0 is returned to indicate this condition.

Otherwise, the value indicates the application's position in the list (with 1 being highest priority, and increasing values indicating decreasing priority).

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_INVALREQUESTMODE, LINEERR_INVALAPPNAME, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL.

Remarks

If LINEERR_INVALMEDIAMODE is returned, the value specified in dwMediaMode is not zero, not a valid extended media mode, and not one of the LINEMEDIAMODE_ Constants, or more than one bit is on in the parameter value.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEEXTENSIONID, VARSTRING


lineGetCallInfo

The lineGetCallInfo function enables an application to obtain fixed information about the specified call.

LONG WINAPI lineGetCallInfo(
  HCALL hCall,
  LPLINECALLINFO lpCallInfo
);

Parameters

hCall
A handle to the call to be queried. The call state of hCall can be any state.
lpCallInfo
A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call-related information. Prior to calling lineGetCallInfo, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

A separate LINECALLINFO structure exists for every incoming or outgoing call. The structure contains primarily fixed information about the call. An application would typically be interested in checking this information when it receives its handle for a call by the LINE_CALLSTATE message, or each time it receives notification by a LINE_CALLINFO message that parts of the call information structure have changed. These messages supply the handle for the call as a parameter.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CALLINFO, LINE_CALLSTATE, LINECALLINFO


lineGetCallStatus

The lineGetCallStatus function returns the current status of the specified call.

LONG WINAPI lineGetCallStatus(
  HCALL hCall,
  LPLINECALLSTATUS lpCallStatus
);

Parameters

hCall
A handle to the call to be queried. The call state of hCall can be any state.
lpCallStatus
A pointer to a variably sized data structure of type LINECALLSTATUS. Upon successful completion of the request, this structure is filled with call status information. Prior to calling lineGetCallStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineGetCallStatus function returns the dynamic status of a call, whereas lineGetCallInfo returns primarily static information about a call. Call status information includes the current call state, detailed mode information related to the call while in this state (if any), as well as a list of the available API functions the application can invoke on the call while the call is in this state. An application would typically be interested in requesting this information when it receives notification about a call state change by the LINE_CALLSTATE message.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINECALLSTATUS, lineGetCallInfo


lineGetConfRelatedCalls

The lineGetConfRelatedCalls function returns a list of call handles that are part of the same conference call as the specified call. The specified call is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls.

LONG WINAPI lineGetConfRelatedCalls(
  HCALL hCall,
  LPLINECALLLIST lpCallList
);

Parameters

hCall
A handle to a call. This is either a conference call or a participant call in a conference call. For a conference parent call, the call state of hCall can be any state. For a conference participant call, it must be in the conferenced state.
lpCallList
A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all calls in the conference call are returned in this structure. The first call in the list is the conference call, the other calls are the participant calls. The application is granted monitor privilege to those calls for which it does not already have handles; the privileges to calls in the list for which the application already has handles is unchanged. Prior to calling lineGetConfRelatedCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOCONFERENCE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The specified call can either be a conference call handle or a handle to a participant call. For example, a consultation call that has not yet been added to a conference call is not part of a conference. The first entry in the list that is returned is the conference call handle, the other handles are all the participant calls. The specified call is always one of the calls returned in the list. Calls in the list to which the application does not already have a call handle are assigned monitor privilege; privileges to calls for which the application already has handles are unchanged. The application can use lineSetCallPrivilege to change the privilege of the call.

If lineGetConfRelatedCalls is called immediately after a call is added to a conference using lineCompleteTransfer, lineGetConfRelatedCalls may not return a complete list of related calls because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference (that is, the conferenced state is confirmed by the service provider). After the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

The application can invoke lineGetCallInfo and lineGetCallStatus for each call in the list to determine the call's information and status, respectively.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, lineCompleteTransfer, lineGetCallInfo, lineGetCallStatus, lineSetCallPrivilege


lineGetCountry

The lineGetCountry function fetches the stored dialing rules and other information related to a specified country/region, the first country/region in the country/region list, or all countries/regions.

LONG WINAPI lineGetCountry(
  DWORD dwCountryID,
  DWORD dwAPIVersion,
  LPLINECOUNTRYLIST lpLineCountryList
);

Parameters

dwCountryID
The country/region identifier (not the country code) of the country/region for which information is to be obtained. If the value 1 is specified, information on the first country/region in the country/region list is obtained. If the value 0 is specified, information on all countries/regions is obtained (which can require a great deal of memory—20 KB or more).
dwAPIVersion
The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpLineCountryList
A pointer to a location to which a LINECOUNTRYLIST structure is loaded. Prior to calling lineGetCountry, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINECOUNTRYLIST, lineNegotiateAPIVersion


lineGetDevCaps

The lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device.

LONG WINAPI lineGetDevCaps(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  LPLINEDEVCAPS lpLineDevCaps
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device to be queried.
dwAPIVersion
The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained by lineNegotiateAPIVersion.
dwExtVersion
The version number of the service provider-specific extensions to be used. This number is obtained by lineNegotiateExtVersion. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.
lpLineDevCaps
A pointer to a variably sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities information. Prior to calling lineGetDevCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALAPPHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

Before using lineGetDevCaps, the application must negotiate the API version number to use, and, if desired, the extension version to use.

The API and extension version numbers are those under which TAPI and the service provider must operate. If version ranges do not overlap, the application, API, or service-provider versions are incompatible and an error is returned.

One of the members in the LINEDEVCAPS structure returned by this function contains the number of addresses assigned to the specified line device. The actual address identifiers used to reference individual addresses vary from zero to one less than the returned number. The capabilities of each address can be different. Use lineGetAddressCaps for each available <dwDeviceID, dwAddressID> combination to determine the exact capabilities of each address. Note that an address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINEDEVCAPS, lineGetAddressCaps, lineNegotiateAPIVersion, lineNegotiateExtVersion


lineGetDevConfig

The lineGetDevConfig function returns an "opaque" data structure object, the contents of which are specific to the line (service provider) and device class. The data structure object stores the current configuration of a media-stream device associated with the line device.

LONG WINAPI lineGetDevConfig(
  DWORD dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.
lpszDeviceClass
A pointer to a null-terminated string that specifies the device class of the device whose configuration is requested. Valid device class lineGetID strings are the same as those specified for the function.

Return Values

Returns zero if the function succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NODEVICE.

Remarks

Call states are device specific.

The lineGetDevConfig function can be used to retrieve a data structure from TAPI that specifies the configuration of a media stream device associated with a particular line device. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

Typically, an application calls lineGetID to identify the media stream device associated with a line, and then calls lineConfigDialog to allow the user to set up the device configuration. It could then call lineGetDevConfig, and save the configuration information in a phone book (or other database) associated with a particular call destination. When the user later wishes to call the same destination again, lineSetDevConfig can be used to restore the configuration settings selected by the user. The functions lineSetDevConfig, lineConfigDialog, and lineGetDevConfig can be used, in that order, to allow the user to view and update the settings.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The structure returned by this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used in lineSetDevConfig to restore the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this can work in some instances, it is not guaranteed).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineConfigDialog, lineGetID, lineSetDevConfig, VARSTRING


lineGetIcon

The lineGetIcon function allows an application to retrieve a service line device-specific (or provider-specific) icon for display to the user.

LONG WINAPI lineGetIcon(
  DWORD dwDeviceID,
  LPCSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The line device whose icon is requested.
lpszDeviceClass
A pointer to a null-terminated string that identifies a device class name. This device class allows the application to select a specific sub-icon applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level icon associated with the line device rather than a specified media stream device would be selected.
lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

The lineGetIcon function causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) that is associated with the specified line. The icon handle is for a resource associated with the provider. The application must use CopyIcon if it wants to reference the icon after the provider is unloaded, which is unlikely to happen as long as the application has the line open.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. The parameters "tapi/line", "", or NULL can be used to request the icon for the line service.

For applications using an API version earlier than 2.0, if the provider does not return an icon (whether because the given device class is invalid or the provider does not support icons), TAPI substitutes a generic Win32 Telephony line device icon. For applications using API version 2.0 or later, TAPI substitutes the default line icon only if the lpszDeviceClass parameter is "tapi/line", "" or NULL. For any other device class, if the given device class is not valid or the provider does not support icons for the class, lineGetIcon returns LINEERR_INVALDEVICECLASS.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineGetID


lineGetID

The lineGetID function returns a device identifier for the specified device class associated with the selected line, address, or call.

LONG WINAPI lineGetID(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  LPVARSTRING lpDeviceID,
  LPCSTR lpszDeviceClass
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
hCall
A handle to a call.
dwSelect
Specifies whether the requested device identifier is associated with the line, address or a single call. This parameter uses one and only one of the LINECALLSELECT_ Constants.
lpDeviceID
A pointer to a memory location of type VARSTRING, where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class API for naming devices. Prior to calling lineGetID, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.
lpszDeviceClass
A pointer to a null-terminated string that specifies the device class of the device whose identifier is requested. Valid device class strings are those used in the SYSTEM.INI section to identify device classes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSELECT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODEVICE, LINEERR_UNINITIALIZED.

Remarks

The lineGetID function can be used to retrieve a line-device identifier when given a line handle. This is useful after lineOpen has been opened using LINEMAPPER as a device identifier in order to determine the real line-device identifier of the opened line. This function can also be used to obtain the device identifier of a phone device or media device (for device classes such as COM, wave, MIDI, phone, line, or NDIS) associated with a call, address or line. This identifier can then be used with the appropriate API (such as phone, MIDI, wave) to select the corresponding media device associated with the specified call.

See TAPI Device Classes for device class names.

A vendor that defines a device-specific media mode also needs to define the corresponding device-specific (proprietary) API to manage devices of the media mode. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies both the vendor and, following it, the media type. For example: "intel/video".

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineOpen, VARSTRING


lineGetLineDevStatus

The lineGetLineDevStatus function enables an application to query the specified open line device for its current status.

LONG WINAPI lineGetLineDevStatus(
  HLINE hLine,
  LPLINEDEVSTATUS lpLineDevStatus
);

Parameters

hLine
A handle to the open line device to be queried.
lpLineDevStatus
A pointer to a variably sized data structure of type LINEDEVSTATUS. Upon successful completion of the request, this structure is filled with the line's device status. Prior to calling lineGetLineDevStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

An application uses lineGetLineDevStatus to query the line device for its current line status. This status information applies globally to all addresses on the line device. Use lineGetAddressStatus to determine status information about a specific address on a line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINEDEVSTATUS, lineGetAddressStatus


lineGetMessage

The lineGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see lineInitializeEx for further details).

LONG WINAPI lineGetMessage(
  HLINEAPP hLineApp,
  LPLINEMESSAGE lpMessage,
  DWORD dwTimeout
);

Parameters

hLineApp
The handle returned by lineInitializeEx. The application must have set the LINEINITIALIZEEXOPTION_USEEVENT option in the dwOptions member of the LINEINITIALIZEEXPARAMS structure.
lpMessage
A pointer to a LINEMESSAGE structure. Upon successful return from this function, the structure contains the next message that had been queued for delivery to the application.
dwTimeout
The time-out interval, in milliseconds. The function returns if the interval elapses, even if no message can be returned. If dwTimeout is zero, the function checks for a queued message and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_NOMEM.

Remarks

If the lineGetMessage function has been called with a non-zero timeout and the application calls lineShutdown on another thread, this function returns immediately with LINEERR_INVALAPPHANDLE.

If the timeout expires (or was zero) and no message could be fetched from the queue, the function returns with the error LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

lineInitializeEx, LINEINITIALIZEEXPARAMS, LINEMESSAGE, lineShutdown


lineGetNewCalls

The lineGetNewCalls function returns call handles to calls on a specified line or address for which the application currently does not have handles. The application is granted monitor privilege to these calls.

LONG WINAPI lineGetNewCalls(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwSelect,
  LPLINECALLLIST lpCallList
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwSelect
The selection of calls that are requested. This parameter uses one and only one of the LINECALLSELECT_ Constants.
lpCallList
A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all selected calls are returned in this structure. Prior to calling lineGetNewCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSELECT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

An application can use lineGetNewCalls to obtain handles to calls for which it currently has no handles. The application can select the calls for which handles are to be returned by basing this selection on scope (calls on a specified line, or calls on a specified address). For example, an application can request call handles to all calls on a given address for which it currently has no handle. The application is always given monitor privilege to the new call handles. Also, when opening a line, an application uses this function to become aware of existing calls.

The application can invoke lineGetCallInfo and lineGetCallStatus for each call in the list to determine the call's information and status, respectively. It can use lineSetCallPrivilege to change its privilege to owner.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINECALLLIST, lineGetCallInfo, lineGetCallStatus, lineSetCallPrivilege


lineGetNumRings

The lineGetNumRings function determines the number of rings an incoming call on the given address should ring prior to answering the call.

LONG WINAPI lineGetNumRings(
  HLINE hLine,
  DWORD dwAddressID,
  LPDWORD lpdwNumRings
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
lpdwNumRings
The number of rings that is the minimum of all current lineSetNumRings requests.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGetNumRings and lineSetNumRings functions, when used in combination, provide a mechanism to support the implementation of toll-saver features across multiple independent applications.

An application that receives a handle for a call in the offering state and a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. The lineGetNumRings function returns the minimum of all applications' number of rings specified by lineSetNumRings. Because this number can vary dynamically, an application should invoke lineGetNumRings each time it has the option to answer a call. If no application has called lineSetNumRings, the number of rings returned is 0xFFFFFFFF. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle.

If call classification is performed by TAPI of answering all calls of unknown media mode and filtering the media stream, TAPI honors this number as well.

Note This operation is purely informational and does not in itself affect the state of any calls on the line device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_LINEDEVSTATE, lineSetNumRings


lineGetProviderList

The lineGetProviderList function returns a list of service providers currently installed in the telephony system.

LONG WINAPI lineGetProviderList(
  DWORD dwAPIVersion,
  LPLINEPROVIDERLIST lpProviderList
);

Parameters

dwAPIVersion
The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpProviderList
A pointer to a memory location where TAPI can return a LINEPROVIDERLIST structure. Prior to calling lineGetProviderList, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, lineNegotiateAPIVersion, LINEPROVIDERLIST


lineGetRequest

The lineGetRequest function retrieves the next by-proxy request for the specified request mode.

LONG WINAPI lineGetRequest(
  HLINEAPP hLineApp,
  DWORD dwRequestMode,
  LPVOID lpRequestBuffer
);

Parameters

hLineApp
The application's usage handle for the line portion of TAPI.
dwRequestMode
The type of request that is to be obtained. Note that dwRequestMode can only have one bit set. This parameter uses One and only one of the LINEREQUESTMODE_ Constants.
lpRequestBuffer
A pointer to a memory buffer where the parameters of the request are to be placed. The size of the buffer and the interpretation of the information placed in the buffer depends on the request mode. The application-allocated buffer is assumed to be of sufficient size to hold the request.

If dwRequestMode is LINEREQUESTMODE_MAKECALL, interpret the content of the request buffer using the LINEREQMAKECALL structure.

If dwRequestMode is LINEREQUESTMODE_MEDIACALL, interpret the content of the request buffer using the LINEREQMEDIACALL structure.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_NOTREGISTERED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOREQUEST.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall. These requests are queued by TAPI and the highest priority application that has registered to handle the request is sent a LINE_REQUEST message with indication of the mode of the request that is pending. Typically, this application is the user's call-control application. The LINE_REQUEST message indicates that zero or more requests may be pending for the registered application to process; after receiving LINE_REQUEST, it is the responsibility of the recipient application to call lineGetRequest until LINEERR_NOREQUEST is returned, indicating that no more requests are pending.

Next, the call-control application that receives this message invokes lineGetRequest, specifying the request mode and a buffer that is large enough to hold the request. The call-control application then interprets and executes the request.

After execution of lineGetRequest, TAPI purges the request from its internal queue, making room available for a subsequent request. It is therefore possible for a new LINE_REQUEST message to be received immediately upon execution of lineGetRequest, should the same or another application issue another request. It is the responsibility of the request recipient application to handle this scenario by some mechanism (for example, by making note of the additional LINE_REQUEST and deferring a subsequent lineGetRequest until processing of the preceding request completes, by getting the subsequent request and buffer as necessary, or by another appropriate means).

The subsequent LINE_REQUEST should not be ignored because it is not repeated by TAPI.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_REQUEST, LINEREQMAKECALL, tapiRequestMakeCall


lineGetStatusMessages

The lineGetStatusMessages function enables an application to query which notification messages the application is set up to receive for events related to status changes for the specified line or any of its addresses.

LONG WINAPI lineGetStatusMessages(
  HLINE hLine,
  LPDWORD lpdwLineStates,
  LPDWORD lpdwAddressStates
);

Parameters

hLine
A handle to the line device.
lpdwLineStates
A bit array that identifies for which line device status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, it is disabled. This parameter uses one or more of the LINEDEVSTATE_ Constants.
lpdwAddressStates
A bit array that identifies for which address status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, disabled. This parameter uses one or more of the LINEADDRESSSTATE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

TAPI defines a number of messages that notify applications about events occurring on lines and addresses. An application may not be interested in receiving all address and line status change messages. The lineSetStatusMessages function can be used to select which messages the application wants to receive. By default, address status and line status reporting is disabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CLOSE, LINE_LINEDEVSTATE, lineSetStatusMessages


lineGetTranslateCaps

The lineGetTranslateCaps function returns address translation capabilities.

LONG WINAPI lineGetTranslateCaps(
  HLINEAPP hLineApp,
  DWORD dwAPIVersion,
  LPLINETRANSLATECAPS lpTranslateCaps
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwAPIVersion
The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpTranslateCaps
A pointer to a location to which a LINETRANSLATECAPS structure is loaded. Prior to calling lineGetTranslateCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODRIVER.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineInitializeEx, lineNegotiateAPIVersion, LINETRANSLATECAPS


lineHandoff

The lineHandoff function gives ownership of the specified call to another application. The application can be either specified directly by its file name or indirectly as the highest priority application that handles calls of the specified media mode.

LONG WINAPI lineHandoff(
  HCALL hCall,
  LPCSTR lpszFileName,
  DWORD dwMediaMode
);

Parameters

hCall
A handle to the call to be handed off. The application must be an owner of the call. The call state of hCall can be any state.
lpszFileName
A pointer to a null-terminated string. If this pointer parameter is non-NULL, it contains the file name of the application that is the target of the handoff. If NULL, the handoff target is the highest priority application that has opened the line for owner privilege for the specified media mode. A valid file name does not include the path of the file.
dwMediaMode
The media mode used to identify the target for the indirect handoff. The dwMediaMode parameter indirectly identifies the target application that is to receive ownership of the call. This parameter is ignored if lpszFileName is not NULL. This parameter uses one and only one of the LINEMEDIAMODE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

Remarks

The lineHandoff function returns LINEERR_TARGETSELF if the calling application attempted an indirect handoff (that is, set the lpszFileName parameter to NULL) and TAPI determined that the application is itself the highest priority application for the given media mode. If LINEERR_TARGETNOTFOUND is returned, a target for the call handoff was not found. This can occur if the named application did not open the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen. Or, in the case of media-mode handoff, no application has opened the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen and with the media mode specified in the dwMediaModes parameter of lineOpen.

Call handoff allows ownership of a call to be passed among applications. There are two types of handoff. In the first type, if the application knows the file name of the target application, it can simply specify that file name. If an instance of the target application has opened the line device, ownership of the call is passed to the other application; otherwise, the handoff fails and an error is returned. This form of handoff succeeds if the call handle is handed off to the same file name as the application requesting the handoff.

The second type of handoff is based on media mode. In this case, the application indirectly specifies the target application by means of a media mode. The highest priority application that has currently opened the line device for that media mode is the target for the handoff. If there is no such application, the handoff fails and an error is returned.

The lineHandoff function does not change the media mode of a call. To change the media mode of a call, the application should use lineSetMediaMode on the call, specifying the new media mode. This changes the call's media mode as stored in the call's LINECALLINFO structure.

If handoff succeeds, the receiving application receives a LINE_CALLSTATE message for the call. This message indicates that the receiving application has owner privilege to the call (dwParam3). In addition, the number of owners and/or monitors for the call may have changed. This is reported by the LINE_CALLINFO message, and the receiving application can then invoke lineGetCallStatus and lineGetCallInfo to retrieve more information about the received call.

The receiving application should first check the media mode in LINECALLINFO. If only a single media mode flag is set, the call is officially of that media mode, and the application can act accordingly. If UNKNOWN and other media mode flags are set, then the media mode of the call is officially UNKNOWN but is assumed to be of one of the media modes for which a flag is set in LINECALLINFO. The application should assume that it ought to probe for the highest priority media mode.

If the probe succeeds (either for that media mode or for another one), the application should set the media mode member in LINECALLINFO to the single media mode that was recognized. If the media mode flag matches the LINECALLINFO media mode, the application can act accordingly. If it makes a determination for another media mode, it must first hand off the call to that media mode.

If the probe fails, the application should clear the corresponding media mode flag in LINECALLINFO and hand off the call, specifying dwMediaMode as LINEMEDIAMODE_UNKNOWN. It should also deallocate its call handle (or revert back to monitoring).

If none of the media modes succeeded in making a determination, only the UNKNOWN flag remains set in the media mode field of LINECALLINFO at the time the media application attempts to hand off the call to UNKNOWN. The final lineHandoff fails if the application is the only remaining owner of the call. This informs the application that it should drop the call and deallocate its handle, in which case the call is abandoned. The privileges of the invoking application to the call are unchanged by this operation, but the application can change its privileges to a call with lineSetCallPrivilege.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Handoffs Overview, TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINECALLINFO, lineGetCallStatus, lineOpen, lineSetCallPrivilege, lineSetMediaMode


lineHold

The lineHold function places the specified call on hold.

LONG WINAPI lineHold(
  HCALL hCall
);

Parameters

hCall
A handle to the call to be placed on hold. The application must be an owner of the call. The call state of hCall must be connected.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

The call on hold is temporarily disconnected allowing the application to use the line device for making or answering other calls. The lineHold function performs a so-called "hard hold" of the specified call (as opposed to a "consultation call"). A call on hard hold typically cannot be transferred or included in a conference call, but a consultation call can. Consultation calls are initiated using lineSetupTransfer, lineSetupConference, or linePrepareAddToConference.

After a call has been successfully placed on hold, the call state typically transitions to onHold. A held call is retrieved by lineUnhold. While a call is on hold, the application can receive LINE_CALLSTATE messages about state changes of the held call. For example, if the held party hangs up, the call state can transition to disconnected.

In a bridged situation, a lineHold operation may possibly not actually place the call on hold, because the status of other stations on the call can govern (for example, attempting to "hold" a call when other stations are participating is not be possible); instead, the call can simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Hold Overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CALLSTATE, linePrepareAddToConference, lineSetupConference, lineSetupTransfer, lineUnhold


lineInitialize

The lineInitialize function is obsolete. It continues to be exported by tapi.dll and tapi32.dll for backward compatibility with applications using API versions 1.3 and 1.4.

Applications using API version 2.0 or later must use lineInitializeEx instead.

For TAPI Versions 1.4 and Earlier

The lineInitialize function initializes the application's use of Tapi.dll for subsequent use of the line abstraction. The function registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in TAPI.

LONG WINAPI lineInitialize(
  LPHLINEAPP lphLineApp,
  HINSTANCE hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR lpszAppName,
  LPDWORD lpdwNumDevs
);

Parameters

lphLineApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls. For more information, see lineCallbackFunc.
lpszAppName
A pointer to a null-terminated text string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call logging purposes. If lpszAppName is NULL, the application's file name is used instead.
lpdwNumDevs
A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Remarks

If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example as a result of adding or removing a telephony service provider), then lineInitialize requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call lineInitialize. If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of anything beyond what is specified by the Basic Telephony subset without first querying their device capabilities using lineGetDevCaps and lineGetAddressCaps.

Applications should not invoke lineInitialize without subsequently opening a line (at least for monitoring). If the application is not monitoring and not using any devices, it should call lineShutdown so that memory resources allocated by tapi.dll can be released if unneeded, and tapi.dll itself can be unloaded from memory while not needed.

Another reason for performing a lineShutdown is that if a user changes the device configuration (adds or removes a line or phone), there is no way for TAPI to notify an application that has a line or phone handle open at the time. After a reconfiguration has taken place, causing a LINEDEVSTATE_REINIT message to be sent, no applications can open a device until all applications have performed a lineShutdown. If any service provider fails to initialize properly, this function fails and returns the error indicated by the service provider.

On all TAPI platforms, lineInitialize is equivalent to lineInitializeEx using the LINEINITIALIZEEXOPTION_USEHIDDENWINDOW option.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

lineCallbackFunc, LINECALLINFO, lineGetAddressCaps, lineGetDevCaps, lineInitializeEx, lineShutdown


lineInitializeEx

The lineInitializeEx function initializes the application's use of TAPI for subsequent use of the line abstraction. It registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in the Telephony API.

LONG WINAPI lineInitializeEx(
  LPHLINEAPP lphLineApp,
  HINSTANCE hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR lpszFriendlyAppName,
  LPDWORD lpdwNumDevs,
  LPDWORD lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Parameters

lphLineApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process (for purposes of identifying call handoff targets and media mode priorities).
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see lineCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
lpszFriendlyAppName
A pointer to a null-terminated text string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call-logging purposes. If lpszFriendlyAppName is NULL, the application's module file name is used instead (as returned by the Windows API GetModuleFileName).
lpdwNumDevs
A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.
lpdwAPIVersion
A pointer to a DWORD-sized location. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of lineNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set. TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI, thereby allowing the application to detect and adapt to having been installed on a system with a different version of TAPI.
lpLineInitializeExParams
A pointer to a structure of type LINEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarks

Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

The Hidden Window mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI verson 1.x applications), TAPI creates a window in the context of the application during the lineInitializeEx or lineInitialize (for TAPI version 1.3 and 1.4 applications) function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage function), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the lineCallbackProc, a pointer to which the application provided as a parameter in its call to lineInitializeEx (or lineInitialize). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the lineShutdown function.

The Event Handle mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEEVENT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent member in LINEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior results; the application can only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI signals this event whenever a telephony event notification is pending for the application; the application must call lineGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the lineShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call lineGetMessage and have it block waiting for a message to be queued.

The Completion Port mechanism is selected by specifying LINEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI sends it using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort member in LINEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey member in LINEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The application retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application has the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a LINEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, it is the application's responsibility to call LocalFree to release the memory used to contain the LINEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling lineShutdown.

When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

If LINEERR_REINIT is returned and TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then lineInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of any particular TAPI function without first querying their device capabilities by lineGetDevCaps and lineGetAddressCaps.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineCallbackFunc, LINECALLINFO, lineGetAddressCaps, lineGetDevCaps, lineGetMessage, lineInitialize, LINEINITIALIZEEXPARAMS, LINEMESSAGE, lineNegotiateAPIVersion, lineShutdown


lineMakeCall

The lineMakeCall function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

LONG WINAPI lineMakeCall(
  HLINE hLine,
  LPHCALL lphCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hLine
A handle to the open line device on which a call is to be originated.
lphCall
A pointer to an HCALL handle. The handle is only valid after the LINE_REPLY message is received by the application indicating that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application is initially the sole owner of this call. This handle is void if the function returns an error (synchronously or asynchronously by the reply message).
lpszDestAddress
A pointer to the destination address. This follows the standard dialable number format. This pointer can be NULL for non-dialed addresses (as with a hot phone) or when all dialing is performed using lineDial. In the latter case, lineMakeCall allocates an available call appearance that would typically remain in the dialtone state until dialing begins. Service providers that have inverse multiplexing capabilities can allow an application to specify multiple addresses at once.
dwCountryCode
The country code of the called party. If a value of 0 is specified, a default is used by the implementation.
lpCallParams
A pointer to a LINECALLPARAMS structure. This structure allows the application to specify how it wants the call to be set up. If NULL is specified, a default 3.1 kHz voice call is established and an arbitrary origination address on the line is selected. This structure allows the application to select elements such as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller ID information, and dialing parameters.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINEHANDLE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_DIALBILLING, LINEERR_INVALPARAM, LINEERR_DIALDIALTONE, LINEERR_INVALPOINTER, LINEERR_DIALPROMPT, LINEERR_INVALRATE, LINEERR_DIALQUIET, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALCALLPARAMS, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE, LINEERR_USERUSERINFOTOOBIG.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE_) in the LINEDEVSTATUS structure. Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineMakeCall have occurred; for example, none of the dialable address prior to the offending character has been dialed, no hookswitch state has changed, and so on.

After dialing has completed, several LINE_CALLSTATE messages are usually sent to the application to notify it about the progress of the call. No generally valid sequence of call-state transitions is specified, as no single fixed sequence of transitions can be guaranteed in practice. A typical sequence can cause a call to transition from dialtone, dialing, proceeding, ringback, to connected. With non-dialed lines, the call can typically transition directly to connected state.

An application has the option to specify an originating address on the specified line device. A service provider that models all stations on a switch as addresses on a single line device allows the application to originate calls from any of these stations using lineMakeCall.

The call parameters allow the application to make non-voice calls or request special call setup options that are not available by default.

An application can partially dial using lineMakeCall and continue dialing using lineDial. To abandon a call attempt, use lineDrop.

After lineMakeCall returns a success reply message to the application, a LINE_CALLSTATE message is sent to the application to indicate the current state of the call. This state is not necessarily LINECALLSTATE_DIALTONE.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, Dialable Addresses, LINE_CALLSTATE, LINE_REPLY, LINECALLPARAMS, LINEDEVSTATUS, lineDial, lineDrop, lineGetLineDevStatus


lineMonitorDigits

The lineMonitorDigits function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode is detected, a message is sent to the application indicating which digit has been detected.

LONG WINAPI lineMonitorDigits(
  HCALL hCall,
  DWORD dwDigitModes
);

Parameters

hCall
A handle to the call on which digits are to be detected. The call state of hCall can be any state except idle or disconnected.
dwDigitModes
The digit mode or modes that are to be monitored. If dwDigitModes is zero, digit monitoring is canceled. This parameter uses one or more of the LINEDIGITMODE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

This function is considered successful if digit monitoring has been correctly initiated, not when digit monitoring has terminated. Digit monitoring remains in effect until it is explicitly disabled by calling lineMonitorDigits with dwDigitModes set to zero, until the call transitions to idle, or when the application deallocates its call handle for the call. Although this function can be invoked in any call state, digits are usually detected only while the call is in the connected state.

Each time a digit is detected, a LINE_MONITORDIGITS message is sent to the application passing the detected digit as a parameter.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. It can use lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

Monitoring of digits on a conference call applies only to the hConfCall, not to the individual participating calls.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_GATHERDIGITS, LINE_MONITORDIGITS, lineGatherDigits


lineMonitorMedia

The lineMonitorMedia function enables and disables the detection of media types (modes) on the specified call. When a media type is detected, a message is sent to the application. For more information, see ITLegacyCallMediaControl::MonitorMedia.

LONG WINAPI lineMonitorMedia(
  HCALL hCall,
  DWORD dwMediaModes
);

Parameters

hCall
A handle to the call. The call state of hCall can be any state except idle.
dwMediaModes
The media types to be monitored. A value of 0 for the dwMediaModes parameter cancels all media type detection. This parameter uses one or more of the LINEMEDIAMODE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The media types specified with lineOpen relate only to enabling the detection of these media types by the service provider for the purpose of handing off new incoming calls to the proper application. They do not impact any of the media-mode notification messages that are expected because of a previous invocation of lineMonitorMedia.

This function is considered successful if media type monitoring has been correctly initiated, not when media type monitoring has terminated. Media monitoring for a given media type remains in effect until it is explicitly disabled by calling lineMonitorMedia with a dwMediaModes parameter set to zero, until the call transitions to idle, or when the application deallocates its call handle for the call. The lineMonitorMedia function is primarily an event reporting mechanism. The media type (mode) of the call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media type. Only the controlling application can change a call's media type.

Default media monitoring performed by the service provider corresponds to the union of all media types specified on lineOpen.

Although this function can be invoked in any call state, a call's media type can typically only be detected while the call is in certain call states. These states can be device specific. For example, in ISDN, a message can indicate the media type of the media stream before the media stream exists. Similarly, distinctive ringing or the called identifier information about the call can be used to identify the media type of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media type by filtering the media stream. Because filtering a call's media stream implies a computational overhead, applications should disable media monitoring when not required. By default, media monitoring is enabled for newly incoming calls, because a call's media type selects the application that should handle the call.

An outgoing application that deals with voice media types may want to monitor the call for silence (a tone) to distinguish who or what is at the called end of a call. For example, a person at home can answer calls with just a short "hello." A person in the office can provide a longer greeting, indicating name and company name. An answering machine can typically have an even longer greeting.

Because media-mode detection enabled by lineMonitorMedia is implemented as a read-only operation of the call's media stream, it is not disruptive.

Monitoring of media on a conference call applies only to the hConfCall parameter, not to the individual participating calls.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINECALLINFO, lineOpen


lineMonitorTones

The lineMonitorTones function enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is sent to the application.

LONG WINAPI lineMonitorTones(
  HCALL hCall,
  LPLINEMONITORTONE const lpToneList,
  DWORD dwNumEntries
);

Parameters

hCall
A handle to the call on whose voice channel tones are to be monitored. The call state of hCall can be any state except idle.
lpToneList
A list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an application-defined tag field that is used to identify individual tones in the list to report a tone detection. Tone monitoring in progress is canceled or changed by calling this operation with either NULL for lpToneList or with another tone list.
dwNumEntries
The number of entries in lpToneList. This parameter is ignored if lpToneList is NULL.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPOINTER, LINEERR_INVALTONE, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Remarks

This function succeeds if tone monitoring has been correctly initiated, not when tone monitoring has terminated. Tone monitoring remains in effect until it is explicitly disabled by calling lineMonitorTones with another tone list (or NULL), until the call transitions to idle, or when the application deallocates its call handle for the call.

Although this function can be invoked in any call state, tones can typically only be detected while the call is in the connected state. Tone detection typically requires computational resources. Depending on the service provider and other activities that compete for such resources, the number of tones that can be detected can vary over time. Also, an equivalent amount of resources can be consumed for monitoring a single triple frequency tone versus three single frequency tones. If resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

The lineMonitorTones function is also used to detect silence. Silence is specified as a tone with a frequency of zero.

Monitoring of tones on a conference call applies only to the hConfCall, not to the individual participating calls

If the LINEERR_INVALPOINTER error value is returned, the specified lpToneList parameter is invalid or the value specified by the dwNumEntries parameter is too large.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEMONITORTONE


lineNegotiateAPIVersion

The lineNegotiateAPIVersion function allows an application to negotiate an API version to use.

LONG WINAPI lineNegotiateAPIVersion(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPILowVersion,
  DWORD dwAPIHighVersion,
  LPDWORD lpdwAPIVersion,
  LPLINEEXTENSIONID lpExtensionID
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device to be queried.
dwAPILowVersion
The least recent TAPI version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
dwAPIHighVersion
The most recent TAPI version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
lpdwAPIVersion
A pointer to a DWORD that contains the TAPI version number that was negotiated. If negotiation succeeds, this number is in the range between dwAPILowVersion and dwAPIHighVersion.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. If the service provider for the specified dwDeviceID supports provider-specific extensions, then, upon a successful negotiation, this structure is filled with the extension identifier of these extensions. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

Use lineInitializeEx to determine the number of line devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of line devices present.

The lineNegotiateAPIVersion function is used to negotiate the API version number to use. It also retrieves the extension identifier supported by the line device, and returns zeros if no extensions are supported. If the application wants to use the extensions defined by the returned extension identifier, it must call lineNegotiateExtVersion to negotiate the extension version to use.

The API version number negotiated is that under which TAPI can operate. If version ranges do not overlap, the application and API or service provider versions are incompatible and an error is returned.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINEEXTENSIONID, lineInitializeEx, lineNegotiateExtVersion, TAPI Versions


lineNegotiateExtVersion

The lineNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified line device. This operation need not be called if the application does not support extensions.

LONG WINAPI lineNegotiateExtVersion(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtLowVersion,
  DWORD dwExtHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device to be queried.
dwAPIVersion
The TAPI version number that was negotiated for the specified line device using lineNegotiateAPIVersion.
dwExtLowVersion
The least recent extension version of the extension identifier returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
dwExtHighVersion
The most recent extension version of the extension identifier returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
lpdwExtVersion
A pointer to a DWORD that contains the extension version number that was negotiated. If negotiation succeeds, this number is in the range between dwExtLowVersion and dwExtHighVersion.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Remarks

Use lineInitializeEx to determine the number of line devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of line devices present.

The lineNegotiateAPIVersion function negotiates the API version number to use. It also retrieves the extension identifier supported by the line device, which is zeros if no extensions are provided. Version numbers should be incremented by one for each release. Leaving gaps in release version numbering can cause unexpected results.

If the application wants to use the extensions defined by the returned extension identifier, it must call lineNegotiateExtVersion to negotiate the extension version to use.

The extension version number negotiated is that under which the application and service provider must both operate. If version ranges do not overlap, the application and service provider versions are incompatible and an error is returned.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Extended Telephony Services Reference, lineInitializeEx, lineNegotiateAPIVersion


lineOpen

The lineOpen function opens the line device specified by its device identifier and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.

LONG WINAPI lineOpen(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  LPHLINE lphLine,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  DWORD_PTR dwCallbackInstance,
  DWORD dwPrivileges,
  DWORD dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hLineApp
A handle to the application's registration with TAPI.
dwDeviceID
Identifies the line device to be opened. It can either be a valid device identifier or the value:
LINEMAPPER
This value is used to open a line device in the system that supports the properties specified in lpCallParams. The application can use lineGetID to determine the identifier of the line device that was opened.
lphLine
A pointer to an HLINE handle that is then loaded with the handle representing the opened line device. Use this handle to identify the device when invoking other functions on the open line device.
dwAPIVersion
The API version number under which the application and Telephony API have agreed to operate. This number is obtained with lineNegotiateAPIVersion.
dwExtVersion
The extension version number under which the application and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained with lineNegotiateExtVersion.
dwCallbackInstance
User-instance data passed back to the application with each message associated with this line or with addresses or calls on this line. This parameter is not interpreted by the Telephony API.
dwPrivileges
The privilege the application wants when notified of a call This parameter contains one or more of the LINECALLPRIVILEGE_ Constants. For applications using TAPI version 2.0 or later, values for this parameter can also be combined with one or more of the LINEOPENOPTION_ Constants.

If the LINEOPENOPTION_SINGLEADDRESS option is specified, then the application is interested only in new calls that appear on the address specified by the dwAddressID member in the LINECALLPARAMS structure pointed to by the lpCallParams parameter (which must be specified).

If LINEOPENOPTION_SINGLEADDRESS is specified but either lpCallParams is invalid or the included dwAddressID does not exist on the line, the open fails with LINERR_INVALADDRESSID.

In addition to setting the dwAddressID member of the LINECALLPARAMS structure to the desired address, the application must also set dwAddressMode in LINECALLPARAMS to LINEADDRESSMODE_ADDRESSID.

The LINEOPENOPTION_SINGLEADDRESS option affects only TAPI's assignment of initial call ownership of calls created by the service provider using a LINE_NEWCALL message. An application that opens the line with LINECALLPRIVILEGE_MONITOR continues to receive monitoring handles to all calls created on the line. Furthermore, the application is not restricted in any way from making calls or performing other operations that affect other addresses on the opened line.

When the LINEOPENOPTION_PROXY option is specified (TAPI 2.0 or higher only), the application must also indicate which specific proxy requests it is prepared to handle. It does so by passing, in the lpCallParams parameter, a pointer to a LINECALLPARAMS structure in which the dwDevSpecificSize and dwDevSpecificOffset members have been set to delimit an array of DWORDs. Each element of this array shall contain one of the LINEPROXYREQUEST_ Constants. For example, a proxy handler application that supports all five of the Agent-related functions would pass in an array of five DWORDs (dwDevSpecificSize would be 20 decimal) containing the five defined LINEPROXYREQUEST_ values.

The proxy request handler application can run on any machine that has authorization to control the line device. However, requests are always routed through the server on which the service provider is executing that actually controls the line device. Thus, it is most efficient if the application handling proxy requests (such as ACD agent control) executes directly on the server along with the service provider.

Subsequent attempts, by the same application or other applications, to open the line device and register to handle the same proxy requests as an application that is already registered fail with LINEERR_NOTREGISTERED.

To stop handling requests on the line, the application simply calls lineClose.

Other flag combinations return the LINEERR_INVALPRIVSELECT error.

dwMediaModes
The media type or modes of interest to the application. This parameter is used to register the application as a potential target for incoming call and call handoff for the specified media type. This parameter is meaningful only if the bit LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored otherwise). This parameter uses one or more of the LINEMEDIAMODE_ Constants.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. This pointer is only used if LINEMAPPER is used; otherwise lpCallParams is ignored. It describes the call parameter that the line device should be able to provide.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Remarks

If LINEERR_ALLOCATED is returned, the line cannot be opened due to a "persistent" condition, such as that of a serial port being exclusively opened by another process. If LINEERR_RESOURCEUNAVAIL is returned, the line cannot be opened due to a dynamic resource overcommitment such as in DSP processor cycles or memory. This overcommitment can be transitory, caused by monitoring of media type or tones, and changes in these activities by other applications can make it possible to reopen the line within a short time period. If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example, as a result of adding or removing a telephony service provider), then lineOpen requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown); at that time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

Opening a line always entitles the application to make calls on any address available on the line. The ability of the application to deal with incoming calls or to be the target of call handoffs on the line is determined by the dwMediaModes parameter. The lineOpen function registers the application as having an interest in monitoring calls or receiving ownership of calls that are of the specified media types. If the application just wants to monitor calls, then it can specify LINECALLPRIVILEGE_MONITOR. If the application just wants to make outgoing calls, it can specify LINECALLPRIVILEGE_NONE. If the application is willing to control unclassified calls (calls of unknown media type), it can specify LINECALLPRIVILEGE_OWNER and LINEMEDIAMODE_UNKNOWN. Otherwise, the application should specify the media type it is interested in handling.

The media types specified with lineOpen add to the default value for the provider's media type monitoring for initial incoming call type determination. The lineMonitorMedia function modifies the mask that controls LINE_MONITORMEDIA messages. If a line device is opened with owner privilege and an extension media type is not registered, then the error LINEERR_INVALMEDIAMODE is returned.

An application that has successfully opened a line device can always initiate calls using lineMakeCall, lineUnpark, linePickup, and lineSetupConference (with a NULL hCall), as well as use lineForward (assuming that doing so is allowed by the device capabilities, line state, and so on).

A single application can specify multiple flags simultaneously to handle multiple media types. Conflicts can arise if multiple applications open the same line device for the same media type. These conflicts are resolved by a priority scheme in which the user assigns relative priorities to the applications. Only the highest priority application for a given media type will ever receive ownership (unsolicited) of a call of that media type. Ownership can be received when an incoming call first arrives or when a call is handed off.

Any application (including any lower priority application) can always acquire ownership with lineGetNewCalls or lineGetConfRelatedCalls. If an application opens a line for monitoring at a time that calls exist on the line, LINE_CALLSTATE messages for those existing calls are not automatically generated to the new monitoring application. The application can query the number of current calls on the line to determine how many calls exist, and, if it wants, it can call lineGetNewCalls to obtain handles to these calls.

An application that handles automated voice should also select the interactive voice open mode and be assigned the lowest priority for interactive voice. The reason for this is that service providers report all voice media types as interactive voice. If media type determination is not performed by the application for the UNKNOWN media type, and no interactive voice application has opened the line device, voice calls would be unable to reach the automated voice application, and would be dropped.

The same application, or different instantiations of the same application, can open the same line multiple times with the same or different parameters.

When an application opens a line device it must specify the negotiated API version and, if it wants to use the line's extensions, it should specify the line's device-specific extension version. These version numbers should have been obtained with lineNegotiateAPIVersion and lineNegotiateExtVersion. Version numbering allows the mixing and matching of different application versions with different API versions and service provider versions.

LINEMAPPER allows an application to select a line indirectly—by means of the services it wants from it. When opening a line device using LINEMAPPER, the following is true: All members from beginning of the LINECALLPARAMS data structure through dwAddressMode are relevant. If dwAddressMode is LINEADDRESSMODE_ADDRESSID it means that any address on the line is acceptable, otherwise if dwAddressMode is LINEADDRESSMODE_DIALABLEADDR, indicating that a specific originating address (phone number) is searched for, or if it is a provider-specific extension, then dwOrigAddressSize/Offset and the portion of the variable part they refer to are also relevant. If dwAddressMode is a provider-specific extension, additional information can be contained in the dwDeviceSpecific variably sized member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_MONITORMEDIA, LINE_PROXYREQUEST, LINECALLPARAMS, lineClose, lineForward, lineGetConfRelatedCalls, lineGetID, lineGetNewCalls, lineInitializeEx, lineMakeCall, lineMonitorMedia, lineNegotiateAPIVersion, lineNegotiateExtVersion, linePickup, lineProxyMessage, lineProxyResponse, lineSetupConference, lineShutdown, lineUnpark


linePark

The linePark function parks the specified call according to the specified park mode.

LONG WINAPI linePark(
  HCALL hCall,
  DWORD dwParkMode,
  LPCSTR lpszDirAddress,
  LPVARSTRING lpNonDirAddress
);

Parameters

hCall
A handle to the call to be parked. The application must be an owner of the call. The call state of hCall must be connected.
dwParkMode
The park mode with which the call is to be parked. This parameter can have only a single flag set, and uses one of the LINEPARKMODE_ Constants.
lpszDirAddress
A pointer to a null-terminated string that indicates the address where the call is to be parked when using directed park. The address is in dialable number format. This parameter is ignored for nondirected park.
lpNonDirAddress
A pointer to a structure of type VARSTRING. For nondirected park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park. Within the VARSTRING structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII string buffer containing a null-terminated string), and the terminating NULL must be accounted for in the dwStringSize. Prior to calling linePark, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARKMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

With directed park, the application determines the address at which it wants to park the call. With nondirected park, the switch determines the address and provides this to the application. In either case, a parked call can be unparked by specifying this address.

The parked call typically enters the idle state after it has been successfully parked, and the application should then deallocate its handle to the call. If the application performs a lineUnpark on the parked call, a new call handle is created for the unparked call even if the application has not deallocated its old call handle.

Some switches can remind the user after a call has been parked for some long amount of time. The application sees an offering call with a call reason set to reminder.

On a nondirected park, if the dwTotalSize member in the VARSTRING structure does not specify a sufficient amount of memory to receive the park address, the corresponding reply message returns a LINEERR_STRUCTURETOOSMALL error value. In such cases, there is no way to retrieve the complete park address. When a LINEERR_STRUCTURETOOSMALL error value is returned, the dwNeededSize member of the NonDirAddress structure does not contain a valid value. If a LINEERR_STRUCTURETOOSMALL error value is received from a nondirected linePark, then increase the size of the buffer and call linePark again until it returns either success or a different LINEERR_XXX result.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Park Overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY, lineUnpark, VARSTRING


linePickup

The linePickup function picks up a call alerting at the specified destination address and returns a call handle for the picked-up call. If invoked with NULL for the lpszDestAddress parameter, a group pickup is performed. If required by the device, lpszGroupID specifies the group identifier to which the alerting station belongs.

LONG WINAPI linePickup(
  HLINE hLine,
  DWORD dwAddressID,
  LPHCALL lphCall,
  LPCSTR lpszDestAddress,
  LPCSTR lpszGroupID
);

Parameters

hLine
A handle to the open line device on which a call is to be picked up.
dwAddressID
The address on hLine at which the pickup is to be originated. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
lphCall
A pointer to a memory location where the handle to the picked up call is returned. The application is the initial sole owner of the call.
lpszDestAddress
A pointer to a null-terminated character buffer that contains the address whose call is to be picked up. The address is in standard dialable address format.
lpszGroupID
A pointer to a null-terminated character buffer containing the group identifier to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

The lpszGroupID parameter can be specified by itself with a NULL pointer for lpszDestAddress. Alternatively, lpszGroupID can be specified in addition to lpszDestAddress, if required by the device.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALGROUPID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

When a call has been picked up successfully, the application is notified by the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It lists the reason for the call as pickup. This structure is available using lineGetCallInfo.

If LINEADDRCAPFLAGS_PICKUPCALLWAIT is TRUE, linePickup can be used to pick up a call for which the user has audibly detected the call-waiting signal but for which the provider is unable to perform the detection. This gives the user a mechanism to "answer" a waiting call even though the service provider was unable to detect the call-waiting signal. Both lpszDestAddress and lpszGroupID pointer parameters must be NULL to pick up a call-waiting call. The linePickup function creates a new call handle for the waiting call and passes that handle to the user. The dwAddressID parameter is most often zero (particularly in single-line residential cases).

After linePickup has been used to pick up the second call, lineSwapHold can be used to toggle between them. The lineDrop function can be used to drop one (and toggle to the other), and so forth. If the user wants to drop the current call and pick up the second call, they should call lineDrop when they get the call-waiting beep, wait for the second call to ring, and then call lineAnswer on the new call handle. The LINEADDRFEATURE_PICKUP flag in the dwAddressFeatures member in LINEADDRESSSTATUS indicates when pickup is actually possible.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Pickup overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CALLSTATE, LINE_REPLY, LINEADDRESSSTATUS, lineAnswer, LINECALLINFO, lineDrop, lineGetCallInfo, lineSwapHold


linePrepareAddToConference

The linePrepareAddToConference function prepares an existing conference call for the addition of another party.

LONG WINAPI linePrepareAddToConference(
  HCALL hConfCall,
  LPHCALL lphConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hConfCall
A handle to a conference call. The application must be an owner of this call. The call state of hConfCall must be connected.
lphConsultCall
A pointer to an HCALL handle. This location is then loaded with a handle identifying the consultation call to be added. Initially, the application is the sole owner of this call.
lpCallParams
A pointer to a LINECALLPARAMS structure containing call parameters to use when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_CALLUNAVAIL, LINEERR_INVALRATE, LINEERR_CONFERENCEFULL, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCONFCALLHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALLINESTATE, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALMEDIAMODE, LINEERR_UNINITIALIZED.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.)

A conference call handle can be obtained with lineSetupConference or with lineCompleteTransfer that is resolved as a three-way conference call. The linePrepareAddToConference function typically places the existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call with lineAddToConference.

The consultation call can be canceled using lineDrop. It may also be possible for an application to swap between the consultation call and the held conference call with lineSwapHold.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Conference overview, Supplementary Line Service Functions, LINE_REPLY, lineAddToConference, lineCompleteTransfer, LINEDEVSTATUS, lineDrop, lineGetLineDevStatus, lineSetupConference, lineSwapHold, LINECALLPARAMS


lineRedirect

The lineRedirect function redirects the specified offering call to the specified destination address.

LONG WINAPI lineRedirect(
  HCALL hCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

hCall
A handle to the call to be redirected. The application must be an owner of the call. The call state of hCall must be offering.
lpszDestAddress
A pointer to the destination address. This follows the standard dialable number format.
dwCountryCode
The country code of the party the call is redirected to. If a value of 0 is specified, a default is used by the implementation.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

Call redirect allows an application to deflect an offering call to another address without first answering the call. Call redirect differs from call forwarding in that call forwarding is performed by the switch without the involvement of the application; redirection can be done on a call-by-call basis by the application, for example, driven by caller ID information. It differs from call transfer in that transferring a call requires the call first be answered.

After a call has been successfully redirected, the call typically transitions to idle.

Besides redirecting an incoming call, an application may have the option to accept the call using lineAccept, reject the call using lineDrop, or answer the call using lineAnswer. The availability of these operations is dependent on device capabilities.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Redirect overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY, lineAccept, lineAnswer, lineDrop


lineRegisterRequestRecipient

The lineRegisterRequestRecipient function registers the invoking application as a recipient of requests for the specified request mode.

LONG WINAPI lineRegisterRequestRecipient(
  HLINEAPP hLineApp,
  DWORD dwRegistrationInstance,
  DWORD dwRequestMode,
  DWORD bEnable
);

Parameters

hLineApp
The application's usage handle for the line portion of TAPI.
dwRegistrationInstance
An application-specific DWORD that is passed back as a parameter of the LINE_REQUEST message. This message notifies the application that a request is pending. This parameter is ignored if bEnable is set to zero. This parameter is examined by TAPI only for registration, not for deregistration. The dwRegistrationInstance value used while deregistering need not match the dwRegistrationInstance used while registering for a request mode.
dwRequestMode
The type or types of request for which the application registers. This parameter uses one or more of the LINEREQUESTMODE_ Constants.
bEnable
If TRUE, the application registers the specified request modes; if FALSE, the application deregisters for the specified request modes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall. Additionally, other applications can request that information be logged with a given call. The tapiRequestMakeCall requests are queued by TAPI, and the highest priority application that has registered to handle the request is sent a LINE_REQUEST message with an indication of the mode of the request that is pending. This application is typically the user's call-control application.

Next, the call-control application that receives this message invokes lineGetRequest, specifying the request mode and a buffer that is large enough to hold the request. The call-control application then interprets and executes the request.

The recipient application is also automatically deregistered for all requests when it does a lineShutdown.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_REQUEST, lineGetRequest, lineShutdown, tapiRequestMakeCall


lineReleaseUserUserInfo

The lineReleaseUserUserInfo function informs the service provider that the application has processed the user-user information contained in the LINECALLINFO structure, and that subsequently received user-user information can now be written into that structure. The service provider sends a LINE_CALLINFO message indicating LINECALLINFOSTATE_USERUSERINFO when new information is available.

LONG WINAPI lineReleaseUserUserInfo(
  HCALL hCall
);

Parameters

hCall
A handle to the call. The application must be an owner of the call. The call state of hCall can be any state.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineReleaseUserUserInfo function allows the application to control the flow of incoming user-user information on an ISDN connection. When a new, complete user-user information message is received, the service provider informs the application using a LINE_CALLINFO message (specifying LINECALLINFOSTATE_USERUSERINFO). Any number of applications can examine the information (using lineGetCallInfo), but the application owning the call controls when the information is released so that subsequent information can be reported. The service provider will not overwrite previous user-user information in LINECALLINFO with newer information until after lineReleaseUserUserInfo has been called. It is the responsibility of the service provider to buffer subsequently received user-user information until the previous information is released by the application owning the call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CALLINFO, LINE_REPLY, LINECALLINFO, lineGetCallInfo


lineRemoveFromConference

The lineRemoveFromConference function removes the specified call from the conference call to which it currently belongs. The remaining calls in the conference call are unaffected.

LONG WINAPI lineRemoveFromConference(
  HCALL hCall
);

Parameters

hCall
A handle to the call to be removed from the conference. The application must be an owner of this call. The call state of hCall must be conferenced.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

This operation removes a party that currently belongs to a conference call. After the call has been successfully removed, it may be possible to further manipulate it using its handle. The availability of this operation and its result are likely to be limited in many implementations. For example, in many implementations, only the most recently added party can be removed from a conference, and the removed call can be automatically dropped (becomes idle). Consult the line's device capabilities to determine the available effects of removing a call from a conference.

If the removal of a participant from a conference is supported, the participant call, after it is removed from the conference, enters the call-state listed in the dwRemoveFromConfState member in LINEADDRESSCAPS.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Conference overview, Supplementary Line Service Functions, LINE_REPLY, LINEADDRESSCAPS


lineRemoveProvider

The lineRemoveProvider function removes an existing telephony service provider from the telephony system.

LONG WINAPI lineRemoveProvider(
  DWORD dwPermanentProviderID,
  HWND hwndOwner
);

Parameters

dwPermanentProviderID
The permanent provider identifier of the service provider to be removed.
hwndOwner
A handle to a window to which any dialog boxes that need to be displayed as part of the removal process (for example, a confirmation dialog box by the service provider's TSPI_providerRemove function) would be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

Remarks

If the call to TSPI_providerRemove succeeds, and the telephony system is active at the time, TAPI calls lineShutdown and/or phoneShutdown on the service provider (depending on which device types are active). Any line or phone handles still held by applications on associated devices are forcibly closed with LINE_CLOSE or PHONE_CLOSE messages (it is preferable for service providers to issue these messages as part of TSPI_providerRemove, after verification with the user). The devices previously under the control of that provider are then marked as "unavailable", so that any future attempts by applications to reference them by device identifier result in LINEERR_NODRIVER.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CLOSE, PHONE_CLOSE


lineSecureCall

The lineSecureCall function secures the call from any interruptions or interference that can affect the call's media stream.

LONG WINAPI lineSecureCall(
  HCALL hCall
);

Parameters

hCall
A handle to the call to be secured. The application must be an owner of the call. The call state of hCall can be any state.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

A call can be secured to avoid interference. For example, in an analog environment, call-waiting tones can destroy a fax or modem session on the original call. The lineSecureCall function allows an existing call to be secured. The lineMakeCall function provides the option to secure the call from the time of call setup. The securing of a call remains in effect for the duration of the call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

Secure a Session overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY, lineMakeCall


lineSendUserUserInfo

The lineSendUserUserInfo function sends user-user information to the remote party on the specified call.

LONG WINAPI lineSendUserUserInfo(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call on which to send user-user information. The application must be an owner of the call. The call state of hCall must be connected, offering, accepted, or ringback.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

This function can be used to send user-user information at any time during a connected call. If the size of the specified information to be sent is larger than what can fit into a single network message (as in ISDN), the service provider is responsible for dividing the information into a sequence of chained network messages (using "more data").

User-user information can also be sent as part of call accept, call reject, and call redirect, and when making calls. User-user information can also be received. The received information is available through the call's call-information record. Whenever user-user information arrives after call offering or prior to call disconnect, a LINE_CALLINFO message with a UserUserInfo parameter notifies the application that user-user information in the call-information record has changed. If multiple network messages are chained, the information is assembled by the service provider and a single message is sent to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_CALLINFO, LINE_REPLY, LINEDEVCAPS


lineSetAppPriority

The lineSetAppPriority function allows an application to set its priority in the handoff priority list for a particular media type or Assisted Telephony request mode, or to remove itself from the priority list.

LONG WINAPI lineSetAppPriority(
  LPCSTR lpszAppFilename,
  DWORD dwMediaMode,
  LPLINEEXTENSIONID lpExtensionID,
  DWORD dwRequestMode,
  LPCSTR lpszExtensionName,
  DWORD dwPriority
);

Parameters

lpszAppFilename
A pointer to a string containing the application executable module filename (without directory information). In TAPI version 2.0 or later, the parameter can specify a filename in either long or 8.3 filename format.
dwMediaMode
The media type for which the priority of the application is to be set. The value can be one of the LINEMEDIAMODE_ Constants; only a single bit may be on. The value zero should be used to set the application priority for Assisted Telephony requests.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. This parameter is ignored.
dwRequestMode
If the dwMediaMode parameter is zero, this parameter specifies the Assisted Telephony request mode for which priority is to be set. It must be either LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL. This parameter is ignored if dwMediaMode is nonzero.
lpszExtensionName
This parameter is ignored.
dwPriority
The new priority for the application. If the value 0 is passed, the application is removed from the priority list for the specified media or request mode (if it was already not present, no error is generated). If the value 1 is passed, the application is inserted as the highest-priority application for the media or request mode (and removed from a lower-priority position, if it was already in the list). Any other value generates an error.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_INVALREQUESTMODE, LINEERR_INVALAPPNAME, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER.

Remarks

If LINEERR_INVALMEDIAMODE is returned, the value specified in dwMediaMode is not zero and not one of the LINEMEDIAMODE_ Constants, or more than one bit is on in the parameter value.

This function updates the stored priority list. If the telephony system is initialized, it also sets the current, active priorities for applications then running; the new priority is used on the next incoming call or lineHandoff based on media type.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEEXTENSIONID, lineHandoff


lineSetAppSpecific

The lineSetAppSpecific function enables an application to set the application-specific field of the specified call's call-information record.

LONG WINAPI lineSetAppSpecific(
  HCALL hCall,
  DWORD dwAppSpecific
);

Parameters

hCall
A handle to the call whose application-specific field needs to be set. The application must be an owner of the call. The call state of hCall can be any state.
dwAppSpecific
The new content of the dwAppSpecific member for the call's LINECALLINFO structure. This value is not interpreted by the Telephony API.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED.

Remarks

The application-specific field in the LINECALLINFO data structure that exists for each call is not interpreted by the Telephony API or any of its service providers. Its usage is entirely defined by the applications. The field can be read from the LINECALLINFO record returned by lineGetCallInfo. However, lineSetAppSpecific must be used to set the field so that changes become visible to other applications. When this field is changed, all other applications with call handles are sent a LINE_CALLINFO message with an indication that the dwAppSpecific member has changed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CALLINFO, LINECALLINFO, lineGetCallInfo


lineSetCallData

The lineSetCallData function sets the CallData member in LINECALLINFO. Depending on the service provider implementation, the CallData member can be propagated to all applications having handles to the call, including those on other machines (through the server), and can travel with the call when it is transferred.

LONG WINAPI lineSetCallData(
  HCALL hCall,
  LPVOID lpCallData,
  DWORD dwSize
);

Parameters

hCall
Handle to the call. The application must have OWNER privilege.
lpCallData
Address of the data to be copied to the CallData member in LINECALLINFO, replacing any existing data.
dwSize
Number of bytes of data to be copied. A value of 0 causes any existing data to be removed.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINECALLINFO


lineSetCallParams

The lineSetCallParams function allows an application to change bearer mode and/or the rate parameters of an existing call.

LONG WINAPI lineSetCallParams(
  HCALL hCall,
  DWORD dwBearerMode,
  DWORD dwMinRate,
  DWORD dwMaxRate,
  LPLINEDIALPARAMS const lpDialParams
);

Parameters

hCall
A handle to the call whose parameters are to be changed. The application must be an owner of the call. The call state of hCall can be any state except idle or disconnected.
dwBearerMode
The new bearer mode for the call. This parameter uses one and only one of the LINEBEARERMODE_ Constants.
dwMinRate
A lower bound for the call's new data rate. The application can accept a new rate as low as this one.
dwMaxRate
An upper bound for the call's new data rate. This is the maximum data rate the application can accept. If an exact data rate is required, dwMinRate and dwMaxRate should be equal.
lpDialParams
A pointer to the new dial parameters for the call, of type LINEDIALPARAMS. This parameter can be left NULL if the call's current dialing parameters are to be used.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_NOTOWNER, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RATEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALRATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

This operation is used to change the parameters of an existing call. Examples of its usage include changing the bearer mode and/or the data rate of an existing call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY, LINEDIALPARAMS


lineSetCallPrivilege

The lineSetCallPrivilege function sets the application's privilege to the specified privilege.

LONG WINAPI lineSetCallPrivilege(
  HCALL hCall,
  DWORD dwCallPrivilege
);

Parameters

hCall
A handle to the call whose privilege is to be set. The call state of hCall can be any state.
dwCallPrivilege
The privilege the application can have for the specified call. This parameter uses one and only one of the LINECALLPRIVILEGE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLPRIVILEGE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

If the application is the sole owner of a non-idle call and can change its privilege to monitor, a LINEERR_INVALCALLSTATE error is returned. The application can also first drop the call using lineDrop to make the call transition to the idle state and then change its privilege.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineDrop


lineSetCallQualityOfService

The lineSetCallQualityOfService function allows the application to attempt to change the quality of service parameters (reserved capacity and performance guarantees) for an existing call. Except for basic parameter validation, this is a straight pass-through to a service provider.

LONG WINAPI lineSetCallQualityOfService(
  HCALL hCall,
  LPVOID lpSendingFlowspec,
  DWORD dwSendingFlowspecSize,
  LPVOID lpReceivingFlowspec,
  DWORD dwReceivingFlowspecSize
);

Parameters

hCall
Handle to the call. The application must have OWNER privilege.
lpSendingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwSendingFlowspecSize
The total size in bytes of the FLOWSPEC structure and accompanying provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure.
lpReceivingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwReceivingFlowspecSize
The total size in bytes of the FLOWSPEC and accompanying provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_INVALRATE, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions


lineSetCallTreatment

The lineSetCallTreatment function sets the sounds a party on a call that is unanswered or on hold hears. Except for basic parameter validation, it is a straight pass-through by TAPI to the service provider.

LONG WINAPI lineSetCallTreatment(
  HCALL hCall,
  DWORD dwTreatment
);

Parameters

hCall
Handle to the call. The application must have OWNER privilege.
dwTreatment
One of the call treatments supported on the address on which the call appears, as indicated by LINEADDRESSCAPS. LINEERR_INVALPARAM is returned if the specified treatment is not supported.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Remarks

The use of call treatment functionality should be limited to controlling of legacy equipment. New equipment is generally designed so that instead of call treatments being generated by external switching equipment, calls would be connected to PC-based audio sources and signals generated using standard Win32 functions such as the multimedia Wave API.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEADDRESSCAPS


lineSetCurrentLocation

The lineSetCurrentLocation function sets the location used as the context for address translation.

LONG WINAPI lineSetCurrentLocation(
  HLINEAPP hLineApp,
  DWORD dwLocation
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwLocation
Specifies a new value for the CurrentLocation entry in the [Locations] section in the registry. It must contain a valid permanent identifier of a Location entry in the [Locations] section, as obtained from lineGetTranslateCaps. If it is valid, the CurrentLocation entry is updated.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLOCATION, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineGetTranslateCaps, lineInitializeEx


lineSetDevConfig

The lineSetDevConfig function allows the application to restore the configuration of a media stream device on a line device to a setup previously obtained using lineGetDevConfig. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

LONG WINAPI lineSetDevConfig(
  DWORD dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD dwSize,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to the opaque configuration data structure that was returned by lineGetDevConfig in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfig. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig.
lpszDeviceClass
A pointer to a null-terminated string that specifies the device class of the device whose configuration is to be set. Valid device class strings are the same as those specified for the lineGetID function.

Return Values

Returns zero if the function succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

Call states are device specific.

Typically, an application calls lineGetID to identify the media stream device associated with a line, and then calls lineConfigDialog to allow the user to set up the device configuration. It could then call lineGetDevConfig and save the configuration information in a phone book or other database associated with a particular call destination. When the user wants to call the same destination again, this lineSetDevConfig function can be used to restore the configuration settings selected by the user. The lineSetDevConfig, lineConfigDialog, and lineGetDevConfig functions can be used, in that order, to allow the user to view and update the settings.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The application must treat it as "opaque" and not manipulate the contents directly. Generally, the structure can be sent using this function only to the same device from which it was obtained. Certain telephony service providers may, however, permit structures to be interchanged between identical devices (that is, multiple ports on the same multiport modem card). Such interchangeability is not guaranteed in any way, even for devices of the same device class.

Some service providers may permit the configuration to be set while a call is active, and others may not.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineConfigDialog, lineGetDevConfig, lineGetID, VARSTRING


lineSetLineDevStatus

The lineSetLineDevStatus function sets the line device status. Except for basic parameter validation, it is a straight pass-through to the service provider. The service provider sends a LINE_LINEDEVSTATE message to inform applications of the new state, when set; TAPI does not synthesize these messages.

LONG WINAPI lineSetLineDevStatus(
  HLINE hLine,
  DWORD dwStatusToChange,
  DWORD fStatus
);

Parameters

hLine
Handle to the line device.
dwStatusToChange
One or more of the LINEDEVSTATUSFLAGS_ Constants.
fStatus
TRUE (–1) to turn on the indicated status bit(s), FALSE (0) to turn off.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALLINESTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.


lineSetMediaControl

The lineSetMediaControl function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media types, custom tones, and call states.

LONG WINAPI lineSetMediaControl(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  LPLINEMEDIACONTROLDIGIT const lpDigitList,
  DWORD dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const lpMediaList,
  DWORD dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const lpToneList,
  DWORD dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD dwCallStateNumEntries
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address identifier on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
hCall
A handle to a call. The application must be an owner of the call. The call state of hCall can be any state.
dwSelect
Specifies whether the media control requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This parameter one and only one of the LINECALLSELECT_ Constants.
lpDigitList
A pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

dwDigitNumEntries
The number of entries in the lpDigitList.
lpMediaList
A pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media type to be monitored, media-type specific information (such as duration), and a media control field. If a media type in the list is detected, the corresponding media control action is performed on the call's media stream.
dwMediaNumEntries
The number of entries in lpMediaList.
lpToneList
A pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media-control field. If a tone in the list is detected, the corresponding media control action is performed on the call's media stream.
dwToneNumEntries
The number of entries in lpToneList.
lpCallStateList
A pointer to an array with entries of type LINEMEDIACONTROLCALLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action. Whenever the given call transitions into one of the call states in the list, the corresponding media control action is invoked.
dwCallStateNumEntries
The number of entries in lpCallStateList.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITLIST, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIALIST, LINEERR_INVALPOINTER, LINEERR_INVALTONELIST.

Remarks

The lineSetMediaControl function is considered successful if media control has been correctly initiated, not when any media control has taken effect. Media control in progress is changed or is canceled by calling this function again with either different parameters or NULLs. If one or more of the parameters lpDigitList, lpMediaList, lpToneList, and lpCallStateList are NULL, then the corresponding digit, media type, tone, or call state-triggered media control is disabled. To modify just a portion of the media control parameters while leaving the remaining settings in effect, the application should invoke lineSetMediaControl, supplying the previous parameters for those portions that must remain in effect and new parameters for those parts that are to be modified.

If hCall is selected and the call terminates or the application deallocates its handle, media control on that call is canceled.

All applications that are owners of the call are in principle allowed to make media control requests on the call. Only a single media control request can be outstanding on a call across all applications that own the call. Each time lineSetMediaControl is called, the new request overrides any media control then in effect on the call, whether set by the calling application or any other owning application.

Depending on the service provider and other activities that compete for such resources, the number of simultaneous detections that can be made can vary over time. If service provider resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

Whether or not media control is supported by the service provider is a device capability.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE


lineSetMediaMode

The lineSetMediaMode function sets the media type(s) of the specified call in its LINECALLINFO structure. For more information, see ITLegacyCallMediaControl::SetMediaType.

LONG WINAPI lineSetMediaMode(
  HCALL hCall,
  DWORD dwMediaModes
);

Parameters

hCall
A handle to the call whose media type is to be changed. The application must be an owner of the call. The call state of hCall can be any state.
dwMediaModes
The new media type(s) for the call. This parameter uses the LINEMEDIAMODE_ Constants. As long as the UNKNOWN media type flag is set, other media type flags may be set as well. This is used to identify a call's media type as not fully determined, but narrowed down to one of a small set of specified media types. If the UNKNOWN flag is not set, only a single media type can be specified.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineSetMediaMode function changes the call's media type in its LINECALLINFO structure. Typical usage of this operation is either to set a call's media type to a specific known media type or to exclude possible media types as long as the call's media type is officially unknown (the UNKNOWN media type flag is set).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINECALLINFO


lineSetNumRings

The lineSetNumRings function sets the number of rings that must occur before an incoming call is answered. This function can be used to implement a toll-saver-style function. It allows multiple independent applications to each register the number of rings. The function lineGetNumRings returns the minimum number of rings requested. It can be used by the application that answers incoming calls to determine the number of rings it should wait before answering the call.

LONG WINAPI lineSetNumRings(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwNumRings
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwNumRings
The number of rings before a call should be answered in order to honor the toll-saver requests from all applications.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The lineGetNumRings and lineSetNumRings functions, when used in combination, provide a mechanism to support the implementation of toll-saver features across multiple independent applications. If no application ever calls lineSetNumRings, lineGetNumRings returns 0xFFFFFFFF.

An application that is the owner of a call in the offering state and that received a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle, so the application should count these messages. If this call disconnects before being answered, and another call comes in shortly thereafter, the LINE_CALLSTATE message should allow the application to determine that ringing is related to the second call.

If call classification is performed by TAPI by means of answering incoming calls of unknown media type and filtering the media stream, TAPI honors this number as well.

Note This operation is purely informational and does not affect the state of any calls on the line device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_LINEDEVSTATE, lineGetNumRings


lineSetStatusMessages

The lineSetStatusMessages function enables an application to specify which notification messages to receive for events related to status changes for the specified line or any of its addresses.

LONG WINAPI lineSetStatusMessages(
  HLINE hLine,
  DWORD dwLineStates,
  DWORD dwAddressStates
);

Parameters

hLine
A handle to the line device.
dwLineStates
A bit array that identifies for which line-device status changes a message is to be sent to the application. This parameter uses one or more of the LINEDEVSTATE_ Constants.
dwAddressStates
A bit array that identifies for which address status changes a message is to be sent to the application. This parameter uses one or more of the LINEADDRESSSTATE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL.

Remarks

TAPI defines a number of messages that notify applications about events occurring on lines and addresses. An application may not be interested in receiving all address and line status change messages. The lineSetStatusMessages function can be used to select which messages the application receives. By default, address and line status reporting is disabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, LINE_CLOSE, LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx, lineOpen


lineSetTerminal

The lineSetTerminal function enables an application to specify which terminal information related to the specified line, address, or call is to be routed. The lineSetTerminal function can be used while calls are in progress on the line to allow an application to route these events to different devices as required.

LONG WINAPI lineSetTerminal(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  DWORD dwTerminalModes,
  DWORD dwTerminalID,
  DWORD bEnable
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
hCall
A handle to a call. The call state of hCall can be any state, if dwSelect is CALL.
dwSelect
Specifies whether the terminal setting is requested for the line, the address, or just the specified call. If line or address is specified, events either apply to the line or address itself or serve as a default initial setting for all new calls on the line or address. This parameter uses one of the LINECALLSELECT_ Constants.
dwTerminalModes
The class or classes of low-level events to be routed to the given terminal. This parameter uses one or more of the LINETERMMODE_ Constants.
dwTerminalID
The device identifier of the terminal device where the given events are to be routed. Terminal identifiers are small integers in the range of zero to one less than dwNumTerminals, where dwNumTerminals, and the terminal modes each terminal is capable of handling, are returned by lineGetDevCaps.

Note These terminal identifiers have no relation to other device identifiers and are defined by the service provider using device capabilities.

bEnable
If TRUE, dwTerminalID is valid and the specified event classes are routed to or from that terminal. If FALSE, these events are not routed to or from the terminal device with identifier equal to dwTerminalID.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTERMINALID, LINEERR_UNINITIALIZED, LINEERR_INVALTERMINALMODE.

Remarks

An application can use this function to route certain classes of low-level line events to the specified terminal device or to suppress the routing of these events. For example, voice can be routed to an audio I/O device (headset), lamps and display events can be routed to the local phone device, and button events and ringer events can be suppressed altogether.

This function can be called at any time, even when a call is active on the given line device. This allows a user to switch from using the local phone set to another audio I/O device. This function can be called multiple times to route the same events to multiple terminals simultaneously. To reroute events to a different terminal, the application should first disable routing to the existing terminal and then route the events to the new terminal.

Terminal identifier assignments are made by the line's service provider. Device capabilities indicate only which terminal identifiers the service provider has available. Service providers that do not support this type of event routing would indicate that they have no terminal devices (dwNumTerminals in LINEDEVCAPS would be zero).

Invoking lineSetTerminal on a line or address affects all existing calls on that line or address, but does not affect calls on other addresses. It also sets the default for future calls on that line or address. A line or address that has multiple connected calls active at one time can have different routing in effect for each call.

Disabling the routing of low-level events to a terminal when these events are not currently routed to or from that terminal does not necessarily generate an error so long as the function succeeds (the specified events are not routed to or from that terminal).

TAPI routes call progress tones and messages to the same location as set by the lineSetTerminal function for "media". For example, if audio signals are going to the phone, then so will busy signals (analog) or Q.931 messages indicating busy (digital).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY, LINEDEVCAPS, lineGetDevCaps


lineSetTollList

The lineSetTollList function manipulates the toll list.

LONG WINAPI lineSetTollList(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  LPCSTR lpszAddressIn,
  DWORD dwTollListOption
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
lpszAddressIn
A pointer to a null-terminated string containing the address from which the prefix information is to be extracted for processing. This parameter must not be NULL, and it must be in the canonical address format.
dwTollListOption
The toll list operation to be performed. This parameter uses one and only one of the LINETOLLLISTOPTION_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALAPPHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_UNINITIALIZED, LINEERR_INVALLOCATION.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineInitializeEx


lineSetupConference

The lineSetupConference function sets up a conference call for the addition of the third party.

LONG WINAPI lineSetupConference(
  HCALL hCall,
  HLINE hLine,
  LPHCALL lphConfCall,
  LPHCALL lphConsultCall,
  DWORD dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hCall
The initial call that identifies the first party of a conference call. In some environments (as described in device capabilities), a call must exist to start a conference call, and the application must be an owner of this call. In other telephony environments, no call initially exists, hCall must be left NULL, and hLine must be specified to identify the line on which the conference call is to be initiated. The call state of hCall must be connected.
hLine
A handle to the line. This handle is used to identify the line device on which to originate the conference call if hCall is NULL. The hLine parameter is ignored if hCall is non-NULL.
lphConfCall
A pointer to an HCALL handle. This location is then loaded with a handle identifying the newly created conference call. The application is the initial sole owner of this call. The call state of hConfCall is not applicable.
lphConsultCall
A pointer to an HCALL handle. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. Initially, the application is the sole owner for this call.
dwNumParties
The expected number of parties in the conference call. This number is passed to the service provider. The service provider is free to do as it pleases with this number: ignore it, use it as a hint to allocate the right size conference bridge inside the switch, and so on.
lpCallParams
A pointer to a LINECALLPARAMS structure containing call parameters to use when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_UNINITIALIZED, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_CONFERENCEFULL, LINEERR_INVALPOINTER, LINEERR_INUSE, LINEERR_INVALRATE, LINEERR_INVALADDRESSMODE, LINEERR_NOMEM, LINEERR_INVALBEARERMODE, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_STRUCTURETOOSMALL, LINEERR_USERUSERINFOTOOBIG.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.) If LINEERR_INVALMEDIAMODE is returned, check for supported media types on the line in the dwMediaModes member in the LINEDEVCAPS structure.

The lineSetupConference function provides two ways to establish a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hCall parameter is a valid call handle that is initially added to the conference call by the lineSetupConference request; hLine is ignored. On switches where conference call setup does not start with an existing call, hCall must be NULL and hLine must be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. The application can then use lineDial to dial the address of the other party.

The conference call typically transitions into the onHoldPendingConference state, the consultation call into the dialtone state, and the initial call (if there is one) into the conferenced state.

A conference call can also be set up by a lineCompleteTransfer that is resolved into a three-way conference. The application may be able to toggle between the consultation call and the conference call using lineSwapHold.

A consultation call can be canceled by invoking lineDrop on it. When dropping a consultation call, the existing conference call typically transitions back to the connected state. The application should observe the LINE_CALLSTATE messages to determine exactly what happens to the calls. For example, if the conference call reverts back to a regular two-party call, the conference call becomes idle and the original participant call can revert to connected.

If an application specifies the handle of the original call (hCall) in a call to the lineUnhold function, both the conference call and the consultation call typically go to idle.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Conference overview, Supplementary Line Service Functions, LINE_CALLSTATE, lineCompleteTransfer, LINEDEVCAPS, LINEDEVSTATUS, lineDial, lineDrop, lineGetLineDevStatus, lineSwapHold, lineUnhold, LINECALLPARAMS


lineSetupTransfer

The lineSetupTransfer function initiates a transfer of the call specified by the hCall parameter. It establishes a consultation call, lphConsultCall, on which the party can be dialed that can become the destination of the transfer. The application acquires owner privilege to the lphConsultCall parameter.

LONG WINAPI lineSetupTransfer(
  HCALL hCall,
  LPHCALL lphConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hCall
The handle of the call to be transferred. The application must be an owner of the call. The call state of hCall must be connected.
lphConsultCall
A pointer to an hCall handle. This location is then loaded with a handle identifying the temporary consultation call. When setting up a call for transfer, a consultation call is automatically allocated that enables lineDial to dial the address associated with the new transfer destination of the call. The originating party can carry on a conversation over this consultation call prior to completing the transfer. The call state of hConsultCall is not applicable.

This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and unhold an existing held call (using lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, by lineMakeCall, to the destination of the transfer. Which forms of transfer are available are specified in the call's address capabilities.

lpCallParams
A pointer to a LINECALLPARAMS structure containing the call parameters to use when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALPOINTER.

Remarks

The lineSetupTransfer function sets up the transfer of the call specified by hCall. The setup phase of a transfer establishes a consultation call that enables the application to send the address of the destination (the party to be transferred to) to the switch, while the call to be transferred is kept on hold. This new call is referred to as a consultation call (hConsultCall) and can be dropped or otherwise manipulated independently of the original call.

When the consultation call has reached the dialtone call state, the application can proceed transferring the call either by dialing the destination address and tracking its progress, or by unholding an existing call. The transfer of the original call to the selected destination is completed using lineCompleteTransfer.

While the consultation call exists, the original call typically transitions to the onholdPendingTransfer state. The application may be able to toggle between the consultation call and the original call by using lineSwapHold. A consultation call can be canceled by invoking lineDrop on it. After dropping a consultation call, the original call typically transitions back to the connected state. If the call state of the original call is onHoldPendingTransfer, the lineUnhold function can be used to recover the call. In this case, the call state of the consultation call is set to idle.

The application can also transfer calls in a single step, without having to deal with the intervening consultation call, by using lineBlindTransfer.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Transfer Overview, TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY, lineBlindTransfer, lineCompleteTransfer, lineDial, lineDrop, lineMakeCall, lineSwapHold, lineUnhold, LINECALLPARAMS


lineShutdown

The lineShutdown function shuts down the application's usage of the line abstraction of the API.

LONG WINAPI lineShutdown(
  HLINEAPP hLineApp
);

Parameters

hLineApp
The application's usage handle for the line API.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

If this function is called when the application has lines open or calls active, the call handles are deleted and TAPI automatically performs the equivalent of a lineClose on each open line. However, it is recommended that applications explicitly close all open lines before invoking lineShutdown. If shutdown is performed while asynchronous requests are outstanding, those requests are canceled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineClose


lineSwapHold

The lineSwapHold function swaps the specified active call with the specified call on consultation hold.

LONG WINAPI lineSwapHold(
  HCALL hActiveCall,
  HCALL hHeldCall
);

Parameters

hActiveCall
The handle to the active call. The application must be an owner of the call. The call state of hActiveCall must be connected.
hHeldCall
The handle to the consultation call. The application must be an owner of the call. The call state of hHeldCall can be onHoldPendingTransfer, onHoldPendingConference, or onHold.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

Swapping the active call with the call on consultation hold allows the application to alternate or toggle between these two calls. This is typical in call waiting.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY


lineTranslateAddress

The lineTranslateAddress function translates the specified address into another format.

LONG WINAPI lineTranslateAddress(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  LPCSTR lpszAddressIn,
  DWORD dwCard,
  DWORD dwTranslateOptions,
  LPLINETRANSLATEOUTPUT lpTranslateOutput
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If a TAPI 2.0 application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL. TAPI 1.4 applications must still call lineInitialize first.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpszAddressIn
A pointer to a null-terminated string containing the address from which the information is to be extracted for translation. Must be in either the canonical address format, or an arbitrary string of dialable digits (non-canonical). This parameter must not be NULL. If the AddressIn contains a subaddress or name field, or additional addresses separated from the first address by CR and LF characters, only the first address is translated.
dwCard
The credit card to be used for dialing. This parameter is only valid if the CARDOVERRIDE bit is set in dwTranslateOptions. This parameter specifies the permanent identifier of a Card entry in the [Cards] section in the registry (as obtained from lineTranslateCaps) that should be used instead of the PreferredCardID specified in the definition of the CurrentLocation. It does not cause the PreferredCardID parameter of the current Location entry in the registry to be modified; the override applies only to the current translation operation. This parameter is ignored if the CARDOVERRIDE bit is not set in dwTranslateOptions.
dwTranslateOptions
The associated operations to be performed prior to the translation of the address into a dialable string. This parameter uses one of the LINETRANSLATEOPTION_ Constants.

Note If you have set the LINETRANSLATEOPTION_CANCELCALLWAITING bit, it is also advisable to set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags member of the LINECALLPARAMS structure (passed in to lineMakeCall through the lpCallParams parameter). This prevents the line device from using dialable digits to suppress call interrupts.

lpTranslateOutput
A pointer to an application-allocated memory area to contain the output of the translation operation, of type LINETRANSLATEOUTPUT. Prior to calling lineTranslateAddress, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_INVALPOINTER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NODRIVER, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCARD, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, Canonical Addresses, Version Negotiation, lineInitializeEx, LINECALLPARAMS, lineNegotiateAPIVersion, LINETRANSLATEOUTPUT


lineTranslateDialog

The lineTranslateDialog function displays an application-modal dialog box that allows the user to change the current location of a phone number about to be dialed, adjust location and calling card parameters, and see the effect.

LONG WINAPI lineTranslateDialog(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  HWND hwndOwner,
  LPCSTR lpszAddressIn
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on the line device indicated by dwDeviceID).
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.
lpszAddressIn
A pointer to a null-terminated string containing a phone number that is used, in the lower portion of the dialog box, to show the effect of the user's changes on the location parameters. The number must be in canonical format; if noncanonical, the phone number portion of the dialog box is not displayed. This pointer can be left NULL, in which case the phone number portion of the dialog box is not displayed. If the lpszAddressIn parameter contains a subaddress or name field, or additional addresses separated from the first address by CR and LF characters, only the first address is used in the dialog box.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_INVALPARAM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_INVALPOINTER, LINEERR_INIFILECORRUPT, LINEERR_NODRIVER, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED.

Remarks

In TAPI version 2.0 or later, it is possible for multiple instances of this dialog box to be opened. In TAPI versions earlier than 2.0, LINEERR_INUSE is returned if the dialog box is already displayed by another application (it cannot be open more than once). In these versions, TAPI brings the existing dialog box to the front, and the error indicates that any particulars related to the address passed in by the current application have not been handled, because that address was not processed by the function.

The application must call lineGetTranslateCaps after this function to obtain any changes the user made to the telephony address translation parameters, and call lineTranslateAddress to obtain a dialable string based on the user's new selections.

If any function related to address translation (for example, lineGetTranslateCaps or lineTranslateAddress) returns LINEERR_INIFILECORRUPT, the application should call lineTranslateDialog. The lineTranslateDialog function detects the errors and corrects them, and reports the action taken to the user. LINEERR_INIFILECORRUPT is returned the first time any of these functions are used after installation of Windows 95, because the parameters are uninitialized (lineTranslateDialog takes care of initializing them, using the user-specified default country/region to select the default country code).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Basic Telephony Services Reference, lineGetTranslateCaps, lineInitializeEx, lineNegotiateAPIVersion, lineTranslateAddress


lineUncompleteCall

The lineUncompleteCall function cancels the specified call completion request on the specified line.

LONG WINAPI lineUncompleteCall(
  HLINE hLine,
  DWORD dwCompletionID
);

Parameters

hLine
A handle to the line device on which a call completion is to be canceled.
dwCompletionID
The completion identifier for the request that is to be canceled.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCOMPLETIONID, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY


lineUnhold

The lineUnhold function retrieves the specified held call.

LONG WINAPI lineUnhold(
  HCALL hCall
);

Parameters

hCall
The handle to the call to be retrieved. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer, or onHoldPendingConference.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY


lineUnpark

The lineUnpark function retrieves the call parked at the specified address and returns a call handle for it.

LONG WINAPI lineUnpark(
  HLINE hLine,
  DWORD dwAddressID,
  LPHCALL lphCall,
  LPCSTR lpszDestAddress
);

Parameters

hLine
A handle to the open line device on which a call is to be unparked.
dwAddressID
The address on hLine at which the unpark is to be originated. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
lphCall
A pointer to the location of type HCALL where the handle to the unparked call is returned. This handle is unrelated to any other handle that might have been previously associated with the retrieved call, such as the handle that might have been associated with the call when it was originally parked. The application is the initial sole owner of this call.
lpszDestAddress
A pointer to a null-terminated character buffer that contains the address where the call is parked. The address is in standard dialable address format.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_REPLY


Phone Device Functions

TAPI supports the following phone device functions:

  • phoneCallbackFunc
  • phoneClose
  • phoneConfigDialog
  • phoneDevSpecific
  • phoneGetButtonInfo
  • phoneGetData
  • phoneGetDevCaps
  • phoneGetDisplay
  • phoneGetGain
  • phoneGetHookSwitch
  • phoneGetIcon
  • phoneGetID
  • phoneGetLamp
  • phoneGetMessage
  • phoneGetRing
  • phoneGetStatus
  • phoneGetStatusMessages
  • phoneGetVolume
  • phoneInitialize
  • phoneInitializeEx
  • phoneNegotiateAPIVersion
  • phoneNegotiateExtVersion
  • phoneOpen
  • phoneSetButtonInfo
  • phoneSetData
  • phoneSetDisplay
  • phoneSetGain
  • phoneSetHookSwitch
  • phoneSetLamp
  • phoneSetRing
  • phoneSetStatusMessages
  • phoneSetVolume
  • phoneShutdown

    For a categorization of TAPI functions by service level and task, see TAPI Quick Function Reference.


phoneCallbackFunc

The phoneCallbackFunc function is a placeholder for the application-supplied function name.

VOID FAR PASCAL phoneCallbackFunc(
  HANDLE hDevice,
  DWORD dwMsg,
  DWORD dwCallbackInstance,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

hDevice
A handle to a phone device associated with the callback.
dwMsg
A line or call device message.
dwCallbackInstance
Callback instance data passed back to the application in the callback. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For more information about the parameters passed to this callback function, see TAPI Messages.

All callbacks occur in the application's context. The callback function must reside in a dynamic-link library (DLL) or application module and be exported in the module-definition file.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.


phoneClose

The phoneClose function closes the specified open phone device.

LONG WINAPI phoneClose(
  HPHONE hPhone
);

Parameters

hPhone
A handle to the open phone device to be closed. If the function succeeds, the handle is no longer valid.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

After the open phone device has been successfully closed, the implementation sends a PHONE_CLOSE message to the application. These messages can also be sent unsolicited as a result of the phone device being reclaimed somehow. An application should therefore be prepared to handle these unsolicited close messages. At the time the phone device is closed, any outstanding asynchronous replies are suppressed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_CLOSE


phoneConfigDialog

The phoneConfigDialog function causes the provider of the specified phone device to display a modal dialog box (attached to the application's hwndOwner parameter) that allows the user to configure parameters related to the phone device specified by dwDeviceID.

LONG WINAPI phoneConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The phone device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.
lpszDeviceClass
A pointer to a null-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INUSE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for phoneGetID. For example, if the phone supports the wave API, passing "wave/in" as lpszDeviceClass would cause the provider to display the parameters related specifically to wave (or at least to start at the corresponding point in a multilevel configuration dialog box chain, eliminating the need to search for relevant parameters).

The lpszDeviceClass parameter should be "tapi/phone", "", or NULL to cause the provider to display the highest level configuration for the phone.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, phoneGetID


phoneDevSpecific

The phoneDevSpecific function is used as a general extension mechanism to enable a Telephony API implementation to provide features not described in the other TAPI functions. The meanings of these extensions are device specific.

LONG WINAPI phoneDevSpecific(
  HPHONE hPhone,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hPhone
A handle to a phone device.
lpParams
A pointer to a memory area used to hold a parameter block. Its interpretation is device specific. The contents of the parameter block are passed unchanged to or from the service provider by TAPI.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONFAILED.

Additional return values are device specific.

Remarks

This operation provides a generic parameter profile. The interpretation of the parameter block is device specific. Indications and replies that are device specific should use the PHONE_DEVSPECIFIC message.

A service provider can provide access to device-specific functions by defining parameters for use with this operation. Applications that want to make use of these device-specific extensions should consult the device-specific (vendor-specific) documentation that describes which extensions are defined. Typicaly, an application that relies on these device-specific extensions is not portable to work with other service-provider environments.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Extended Telephony Services Reference, PHONE_DEVSPECIFIC, PHONE_REPLY


phoneGetButtonInfo

The phoneGetButtonInfo function returns information about the specified button.

LONG WINAPI phoneGetButtonInfo(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO lpButtonInfo
);

Parameters

hPhone
A handle to the open phone device.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode and the function, and provides additional descriptive text corresponding to the button.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONEBUTTONINFO


phoneGetData

The phoneGetData function uploads the information from the specified location in the open phone device to the specified buffer.

LONG WINAPI phoneGetData(
  HPHONE hPhone,
  DWORD dwDataID,
  LPVOID lpData,
  DWORD dwSize
);

Parameters

hPhone
A handle to the open phone device.
dwDataID
Where in the phone device the buffer is to be uploaded from.
lpData
A pointer to the memory buffer where the data is to be uploaded.
dwSize
The size of the data buffer in bytes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDATAID, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

The function uploads a maximum of dwSize bytes from the phone device into the memory area pointed to by lpData. If dwSize is zero, nothing is copied. The size of each data area is listed in the phone's device capabilities.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions


phoneGetDevCaps

The phoneGetDevCaps function queries a specified phone device to determine its telephony capabilities.

LONG WINAPI phoneGetDevCaps(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  LPPHONECAPS lpPhoneCaps
);

Parameters

hPhoneApp
The handle to the application's registration with TAPI.
dwDeviceID
The phone device to be queried.
dwAPIVersion
The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained with the function phoneNegotiateAPIVersion.
dwExtVersion
The version number of the service provider-specific extensions to be used. This number is obtained with the function phoneNegotiateExtVersion. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.
lpPhoneCaps
A pointer to a variably sized structure of type PHONECAPS. Upon successful completion of the request, this structure is filled with phone device capabilities information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_INVALPOINTER, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_NOMEM, PHONEERR_STRUCTURETOOSMALL, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

Before using phoneGetDevCaps, the application must negotiate the TAPI version number to use (see phoneNegotiateAPIVersion) and, optionally, the extension version to use (see phoneNegotiateExtVersion).

TAPI and extension version numbers are those under which TAPI, Telephony DLL, and service provider must operate. If version ranges do not overlap, the application and API or service-provider versions are incompatible and an error is returned.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONECAPS, phoneNegotiateAPIVersion, phoneNegotiateExtVersion


phoneGetDisplay

The phoneGetDisplay function returns the current contents of the specified phone display.

LONG WINAPI phoneGetDisplay(
  HPHONE hPhone,
  LPVARSTRING lpDisplay
);

Parameters

hPhone
A handle to the open phone device.
lpDisplay
A pointer to the memory location where the display content is to be stored, of type VARSTRING.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM.

Remarks

The lpDisplay memory area should be at least (dwDisplayNumRows * dwDisplayNumColumns) elements in size to receive all of the display information. The dwDisplayNumRows and dwDisplayNumColumns members are available in the PHONECAPS structure returned by phoneGetDevCaps.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONECAPS, phoneGetDevCaps, VARSTRING


phoneGetGain

The phoneGetGain function returns the gain setting of the microphone of the specified phone's hookswitch device.

LONG WINAPI phoneGetGain(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwGain
);

Parameters

hPhone
A handle to the open phone device.
dwHookSwitchDev
The hookswitch device whose gain level is queried. The dwHookSwitchDev parameter can have only one bit set. This parameter uses one and only one of the PHONEHOOKSWITCHDEV_ Constants.
lpdwGain
A pointer to a DWORD containing the current gain setting of the hookswitch microphone component. The dwGain parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service provider-specific.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions


phoneGetHookSwitch

The phoneGetHookSwitch function returns the current hookswitch mode of the specified open phone device.

LONG WINAPI phoneGetHookSwitch(
  HPHONE hPhone,
  LPDWORD lpdwHookSwitchDevs
);

Parameters

hPhone
A handle to the open phone device.
lpdwHookSwitchDevs
A pointer to a DWORD to be filled with the mode of the phone's hookswitch devices. If a bit position is FALSE, the corresponding hookswitch device is onhook; if TRUE, the microphone and/or speaker part of the corresponding hookswitch device is offhook. To find out whether the microphone and/or speaker are enabled, the application can use phoneGetStatus. This parameter uses one or more of the PHONEHOOKSWITCHDEV_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

After the hookswitch state of a device changes, and if hookswitch monitoring is enabled, the application is sent a PHONE_STATE message.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_STATE, phoneGetStatus


phoneGetIcon

The phoneGetIcon function allows an application to retrieve a service phone device-specific (or provider-specific) icon that can be displayed to the user.

LONG WINAPI phoneGetIcon(
  DWORD dwDeviceID,
  LPCSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The phone device whose icon is requested.
lpszDeviceClass
A pointer to a null-terminated string that identifies a device class name. This device class allows the application to select a specific sub-icon applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level icon associated with the phone device rather than a specified media stream device would be selected.
lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_BADDEVICEID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM, PHONEERR_NODEVICE.

Remarks

The phoneGetIcon function causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) associated with the specified phone. The icon handle is for a resource associated with the provider; the application must use CopyIcon if it wants to reference the icon after the provider is unloaded, which is unlikely to happen as long as the application has the phone open.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for phoneGetID. For example, if the phone supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. The parameters "tapi/phone", "", or NULL can be used to request the icon for the phone service.

For applications using a TAPI version earlier than 2.0, if the provider does not return an icon (whether because the given device class is invalid or the provider does not support icons), TAPI substitutes a generic Win32 Telephony phone device icon. For applications using TAPI version 2.0 or later, TAPI substitutes the default phone icon only if the lpszDeviceClass parameter is "tapi/phone", "", or NULL. For any other device class, if the given device class is not valid or the provider does not support icons for the class, phoneGetIcon returns PHONEERR_INVALDEVICECLASS.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, phoneGetID


phoneGetID

The phoneGetID function returns a device identifier for the given device class associated with the specified phone device.

LONG WINAPI phoneGetID(
  HPHONE hPhone,
  LPVARSTRING lpDeviceID,
  LPCSTR lpszDeviceClass
);

Parameters

hPhone
A handle to an open phone device.
lpDeviceID
A pointer to a data structure of type VARSTRING where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class (API) for naming devices.
lpszDeviceClass
A pointer to a null-terminated string that specifies the device class of the device whose identifier is requested. Valid device class strings are those used in the system.ini section to identify device classes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONFAILED, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL.

Remarks

The phoneGetID function can be used to retrieve a phone device identifier given a phone handle. It can also be used to obtain the device identifier of the media device (for device classes such as COM, wave, MIDI, phone, line, or NDIS) associated with the opened phone device. The names of these device class are not case sensitive. This identifier can then be used with the appropriate media API to select the corresponding device.

See TAPI Device Classes for device class names.

A vendor that defines a device-specific media type also needs to define the corresponding device-specific (proprietary) API to manage devices of the media type. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies both the vendor and, following it, the media type. For example: "intel/video".

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, VARSTRING


phoneGetLamp

The phoneGetLamp function returns the current lamp mode of the specified lamp.

LONG WINAPI phoneGetLamp(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  LPDWORD lpdwLampMode
);

Parameters

hPhone
A handle to the open phone device.
dwButtonLampID
The identifier of the lamp to be queried.
lpdwLampMode
A pointer to a memory location that holds the lamp mode status of the given lamp. This parameter uses one and only one of the PHONELAMPMODE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

Phone sets that have multiple lamps per button should be modeled using multiple button/lamp pairs. Each extra button/lamp pair should use a DUMMY button.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions


phoneGetMessage

The phoneGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see phoneInitializeEx for further details).

LONG WINAPI phoneGetMessage(
  HPHONEAPP hPhoneApp,
  LPPHONEMESSAGE lpMessage,
  DWORD dwTimeout
);

Parameters

hPhoneApp
The handle returned by phoneInitializeEx. The application must have set the PHONEINITIALIZEEXOPTION_USEEVENT option in the dwOptions member of the PHONEINITIALIZEEXPARAMS structure.
lpMessage
A pointer to a PHONEMESSAGE structure. Upon successful return from this function, the structure contains the next message that had been queued for delivery to the application.
dwTimeout
The time-out interval, in milliseconds. The function returns if the interval elapses, even if no message can be returned. If dwTimeout is zero, the function checks for a queued message and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPOINTER, PHONEERR_NOMEM.

Remarks

If this function has been called with a nonzero timeout and the application calls phoneShutdown on another thread, this function returns immediately with PHONEERR_INVALAPPHANDLE.

If the timeout expires (or was zero) and no message could be fetched from the queue, the function returns with the error PHONEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

phoneInitializeEx, PHONEINITIALIZEEXPARAMS, PHONEMESSAGE, phoneShutdown


phoneGetRing

The phoneGetRing function enables an application to query the specified open phone device as to its current ring mode.

LONG WINAPI phoneGetRing(
  HPHONE hPhone,
  LPDWORD lpdwRingMode,
  LPDWORD lpdwVolume
);

Parameters

hPhone
A handle to the open phone device.
lpdwRingMode
The ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.
lpdwVolume
The volume level with which the phone is ringing. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions


phoneGetStatus

The phoneGetStatus function enables an application to query the specified open phone device for its overall status.

LONG WINAPI phoneGetStatus(
  HPHONE hPhone,
  LPPHONESTATUS lpPhoneStatus
);

Parameters

hPhone
A handle to the open phone device to be queried.
lpPhoneStatus
A pointer to a variably sized data structure of type PHONESTATUS, which is loaded with the returned information about the phone's status.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

An application can use this function to determine the current state of an open phone device. The status information describes information about the phone device's hookswitch devices, ringer, volume, display, and lamps.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONESTATUS


phoneGetStatusMessages

The phoneGetStatusMessages function returns which phone-state changes on the specified phone device generate a callback to the application.

LONG WINAPI phoneGetStatusMessages(
  HPHONE hPhone,
  LPDWORD lpdwPhoneStates,
  LPDWORD lpdwButtonModes,
  LPDWORD lpdwButtonStates
);

Parameters

hPhone
A handle to the open phone device to be monitored.
lpdwPhoneStates
A pointer to a DWORD holding zero, one or more of the PHONESTATE_ Constants. These flags specify the set of phone status changes and events for which the application can receive notification messages. Monitoring can be individually enabled and disabled for:
lpdwButtonModes
A pointer to a DWORD containing flags that specify the set of phone-button modes for which the application can receive notification messages. This parameter uses zero, one or more of the PHONEBUTTONMODE_ Constants.
lpdwButtonStates
A pointer to a DWORD that contains flags specifying the set of phone button state changes for which the application can receive notification messages. This parameter uses zero, one or more of the PHONEBUTTONSTATE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_UNINITIALIZED.

Remarks

An application can use phoneGetStatusMessages to query the generation of the corresponding messages. Message generation can be controlled by phoneSetStatusMessages. All phone status messages are disabled by default.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneSetStatusMessages


phoneGetVolume

The phoneGetVolume function returns the volume setting of the specified phone's hookswitch device.

LONG WINAPI phoneGetVolume(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwVolume
);

Parameters

hPhone
A handle to the open phone device.
dwHookSwitchDev
A single hookswitch device whose volume level is queried. This parameter uses one of the PHONEHOOKSWITCHDEV_ Constants.
lpdwVolume
A pointer to a DWORD. The function returns the current volume setting of the hookswitch device in this location. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions


phoneInitialize

The phoneInitialize function is obsolete. It continues to be exported by tapi.dll and tapi32.dll for backward compatibility with applications using TAPI versions 1.3 and 1.4.

Applications using TAPI version 2.0 or later must use phoneInitializeEx instead.

For TAPI Versions 1.4 and Earlier

The phoneInitialize function initializes the application's use of TAPI for the subsequent use of the phone functions in the Telephony API. It registers the application's specified notification mechanism and returns the number of phone devices that are available to the application.

LONG WINAPI phoneInitialize(
  LPHPHONEAPP lphPhoneApp,
  HINSTANCE hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR lpszAppName,
  LPDWORD lpdwNumDevs
);

Parameters

lphPhoneApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the phone device.
lpszAppName
A pointer to a null-terminated string that contains displayable characters. If this parameter is non-NULL, it contains an application-supplied name of the application. This name is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application is the current owner of the phone device. This information can be useful for logging and status reporting purposes. If lpszAppName is NULL, the application's filename is used instead.
lpdwNumDevs
A pointer to DWORD. This location is loaded with the number of phone devices available to the application.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPNAME, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

Remarks

The application can refer to individual phone devices by using phone device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these phone devices are capable of anything beyond what is specified by the Assisted Telephony subset without first querying their device capabilities with the phoneGetDevCaps function.

Applications should not invoke phoneInitialize without subsequently opening a phone (at least for monitoring). If the application is not monitoring and not using any devices, it should call phoneShutdown so that memory resources allocated by TAPI can be released if unneeded, and TAPI itself can be unloaded from memory while not needed.

Another reason for performing a phoneShutdown is that if a user changes the device configuration (adds or removes a line or phone), there is no way for TAPI to notify an application that has a line or phone handle open at the time. After a reconfiguration has taken place, causing a PHONESTATE_REINIT message to be sent, no applications can open a device until all applications have performed a phoneShutdown.

If any service provider fails to initialize properly, the phoneInitialize function fails and returns the error indicated by the service provider. If the PHONEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

phoneGetDevCaps, phoneInitializeEx, phoneShutdown, PHONESTATUS


phoneInitializeEx

The phoneInitializeEx function initializes the application's use of TAPI for subsequent use of the phone abstraction. It registers the application's specified notification mechanism and returns the number of phone devices available to the application. A phone device is any device that provides an implementation for the phone-prefixed functions in the Telephony API.

LONG WINAPI phoneInitializeEx(
  LPHPHONEAPP lphPhoneApp,
  HINSTANCE hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR lpszFriendlyAppName,
  LPDWORD lpdwNumDevs,
  LPDWORD lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Parameters

lphPhoneApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see phoneCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
lpszFriendlyAppName
A pointer to a null-terminated string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application has ownership of the phone device. If lpszFriendlyAppName is NULL, the application's module filename is used instead (as returned by the Windows function GetModuleFileName).
lpdwNumDevs
A pointer to a DWORD. Upon successful completion of this request, this location is filled with the number of phone devices available to the application.
lpdwAPIVersion
A pointer to a DWORD. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of phoneNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set. TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI, thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.
lpPhoneInitializeExParams
A pointer to a structure of type PHONEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Remarks

Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

  • The Hidden Window mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI version 1.x applications), TAPI creates a window in the context of the application during the phoneInitializeEx function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage function), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the phoneCallbackFunc, a pointer to which the application provided as a parameter in its call to phoneInitializeEx (or phoneInitialize, for TAPI version 1.3 and 1.4 applications). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the phoneShutdown function.
  • The Event Handle mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEEVENT in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent member in PHONEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior results; the application can only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI signals this event whenever a telephony event notification is pending for the application; the application must call phoneGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the phoneShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call phoneGetMessage and have it block waiting for a message to be queued.
  • The Completion Port mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI sends it to the application using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort member in PHONEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey member in PHONEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The applications retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application has the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a PHONEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, the application must call LocalFree to release the memory used to contain the PHONEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling phoneShutdown.

When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

If PHONEERR_REINIT is returned and TAPI reinitialization has been requested (for example, as a result of adding or removing a telephony service provider), then phoneInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using phoneShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call phoneInitializeEx.

If the PHONEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual phone devices by using phone device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these phone devices are capable of any particular TAPI function without first querying their device capabilities by phoneGetDevCaps.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, phoneCallbackFunc, phoneGetDevCaps, phoneGetMessage, PHONEINITIALIZEEXPARAMS, PHONEMESSAGE, phoneNegotiateAPIVersion, phoneShutdown, PHONESTATUS


phoneNegotiateAPIVersion

The phoneNegotiateAPIVersion allows an application to negotiate an API version to use for the specified phone device.

LONG WINAPI phoneNegotiateAPIVersion(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  DWORD dwAPILowVersion,
  DWORD dwAPIHighVersion,
  LPDWORD lpdwAPIVersion,
  LPPHONEEXTENSIONID lpExtensionID
);

Parameters

hPhoneApp
The handle to the application's registration with TAPI.
dwDeviceID
The phone device to be queried.
dwAPILowVersion
The least recent API version the application is compliant with. The high-order word is the major version number, the low-order word is the minor version number.
dwAPIHighVersion
The most recent API version the application is compliant with. The high-order word is the major version number, the low-order word is the minor version number.
lpdwAPIVersion
A pointer to a DWORD in which the API version number that was negotiated will be returned. If negotiation succeeds, this number is in the range dwAPILowVersion to dwAPIHighVersion.
lpExtensionID
A pointer to a structure of type PHONEEXTENSIONID. If the service provider for the specified dwDeviceID parameter supports provider-specific extensions, this structure is filled with the extension identifier of these extensions when negotiation succeeds. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODRIVER, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

The phoneNegotiateAPIVersion function is used to negotiate the API version number to use with the specified phone device. It returns the extension identifier supported by the phone device, or zeros if no extensions are provided.

If the application wants to use the extensions defined by the returned extension identifier, it must call phoneNegotiateExtVersion to negotiate the extension version to use.

Use phoneInitializeEx to determine the number of phone devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of phone devices present.

The API version number negotiated is that under which TAPI can operate. If version ranges do not overlap, the application, API, or service-provider versions are incompatible and an error is returned.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, TAPI Versions, PHONEEXTENSIONID, phoneInitializeEx, phoneNegotiateExtVersion


phoneNegotiateExtVersion

The phoneNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified phone device. This operation need not be called if the application does not support extensions.

LONG WINAPI phoneNegotiateExtVersion(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtLowVersion,
  DWORD dwExtHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

hPhoneApp
The handle to the application's registration with TAPI.
dwDeviceID
The phone device to be queried.
dwAPIVersion
The API version number that was negotiated for the specified phone device using phoneNegotiateAPIVersion.
dwExtLowVersion
The least recent extension version of the extension identifier returned by phoneNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
dwExtHighVersion
The most recent extension version of the extension identifier returned by phoneNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
lpdwExtVersion
A pointer to a DWORD in which the extension version number that was negotiated is returned. If negotiation succeeds, this number is in the range dwExtLowVersion to dwExtHighVersion.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODRIVER, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_UNINITIALIZED, PHONEERR_INVALPOINTER, PHONEERR_NODEVICE.

Remarks

The phoneNegotiateAPIVersion function is used to negotiate the API version number to use. It returns the extension identifier supported by the phone device, or zeros if no extensions are provided.

In order for the application to use the extensions defined by the returned extension identifier, it must call phoneNegotiateExtVersion to negotiate the extension version to use.

Use phoneInitializeEx to determine the number of phone devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of phone devices present.

The extension version number negotiated is that under which the application and service provider must both operate. If version ranges do not overlap, the application and service-provider versions are incompatible and an error is returned.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Extended Telephony Services Reference, phoneInitializeEx, phoneNegotiateAPIVersion


phoneOpen

The phoneOpen function opens the specified phone device. A phone device can be opened using either owner privilege or monitor privilege. An application that opens the phone with owner privilege can control the phone's lamps, display, ringer, and hookswitch or hookswitches. An application that opens the phone device with monitor privilege is notified only about events that occur at the phone, such as hookswitch changes or button presses.

Ownership of a phone device is exclusive. In other words, only one application can have a phone device opened with owner privilege at a time. The phone device can, however, be opened multiple times with monitor privilege.

LONG WINAPI phoneOpen(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  LPHPHONE lphPhone,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  DWORD_PTR dwCallbackInstance,
  DWORD dwPrivilege
);

Parameters

hPhoneApp
A handle to the application's registration with TAPI.
dwDeviceID
The phone device to be opened.
lphPhone
A pointer to an HPHONE handle that identifies the open phone device. Use this handle to identify the device when invoking other phone control functions.
dwAPIVersion
The API version number under which the application and Telephony API have agreed to operate. This number is obtained from phoneNegotiateAPIVersion.
dwExtVersion
The extension version number under which the application and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained from phoneNegotiateExtVersion.
dwCallbackInstance
User instance data passed back to the application with each message. This parameter is not interpreted by the Telephony API.
dwPrivilege
The privilege requested. This parameter uses one and only one of the PHONEPRIVILEGE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_INVALPRIVILEGE, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

Remarks

When opening a phone device with monitor privileges, the application is sent messages when events occur that change the status of the phone. Messages sent to the application include PHONE_BUTTON and PHONE_STATE. The latter provides an indication of the phone's status item that has changed.

When opening a phone with owner privilege, the phone device can be manipulated in ways that affect the state of the phone device. An application should only open a phone using owner privilege if it actively wants to manipulate the phone device, and it should close the phone device when finished to allow other applications to control the phone.

When an application opens a phone device, it must specify the negotiated API version and, if it wants to use the phone's extensions, the phone's device-specific extension version. This version number should have been obtained with the phoneNegotiateAPIVersion and phoneNegotiateExtVersion functions. Version numbering allows the mix and match of different application versions with different API versions and service-provider versions.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_BUTTON, PHONE_STATE, phoneNegotiateAPIVersion, phoneNegotiateExtVersion


phoneSetButtonInfo

The phoneSetButtonInfo function sets information about the specified button on the specified phone.

LONG WINAPI phoneSetButtonInfo(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO const lpButtonInfo
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone device.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode, the function, and provides additional descriptive text about the button.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALBUTTONLAMPID, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONEHANDLE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY, PHONEBUTTONINFO


phoneSetData

The phoneSetData function downloads the information in the specified buffer to the opened phone device at the selected data identifier.

LONG WINAPI phoneSetData(
  HPHONE hPhone,
  DWORD dwDataID,
  LPVOID const lpData,
  DWORD dwSize
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwDataID
Where in the phone device the buffer is to be downloaded.
lpData
A pointer to the memory location where the data is to be downloaded from.
dwSize
The size of the buffer, in bytes.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALDATAID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED.

Remarks

The phoneSetData function downloads a maximum of dwSize bytes from lpData to the phone device. The format of the data, its meaning to the phone device, and the meaning of the data identifier are service provider-specific. The data in the buffer or the selection of a data identifier may act as commands to the phone device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY


phoneSetDisplay

The phoneSetDisplay function causes the specified string to be displayed on the specified open phone device.

LONG WINAPI phoneSetDisplay(
  HPHONE hPhone,
  DWORD dwRow,
  DWORD dwColumn,
  LPCSTR lpsDisplay,
  DWORD dwSize
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwRow
The row position on the display where the new text is to be displayed.
dwColumn
The column position on the display where the new text is to be displayed.
lpsDisplay
A pointer to the memory location where the display content is stored. The display information must have the format specified in the dwStringFormat member of the phone's device capabilities.
dwSize
The size in bytes of the information pointed to by lpsDisplay.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_INVALPARAM, PHONEERR_RESOURCEUNAVAIL.

Remarks

The specified display information is written to the phone's display, starting at the specified positions. This operation overwrites previously displayed information. If the amount of information exceeds the size of the display, the information is truncated. The amount of information that can be displayed is at most (dwNumRows * dwNumColumns) elements in size. dwNumRows and dwNumColumns are available in the PHONECAPS structure, which is returned by phoneGetDevCaps; they are zero-based.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY, PHONECAPS, phoneGetDevCaps


phoneSetGain

The phoneSetGain function sets the gain of the microphone of the specified hookswitch device to the specified gain level.

LONG WINAPI phoneSetGain(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  DWORD dwGain
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwHookSwitchDev
The hookswitch device whose microphone's gain is to be set. This parameter uses one and only one of the PHONEHOOKSWITCHDEV_ Constants.
dwGain
A pointer to a DWORD containing the new gain setting of the device. The dwGain parameter specifies the gain level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service provider-specific. A value for dwGain that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY


phoneSetHookSwitch

The phoneSetHookSwitch function sets the hook state of the specified open phone's hookswitch devices to the specified mode. Only the hookswitch state of the hookswitch devices listed is affected.

LONG WINAPI phoneSetHookSwitch(
  HPHONE hPhone,
  DWORD dwHookSwitchDevs,
  DWORD dwHookSwitchMode
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwHookSwitchDevs
The device or devices whose hookswitch mode is to be set. This parameter uses one and only one of the PHONEHOOKSWITCHDEV_ Constants.
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
dwHookSwitchMode
The hookswitch mode to set. This parameter uses one and only one of the PHONEHOOKSWITCHMODE_ Constants.
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALHOOKSWITCHMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED.

Remarks

The hookswitch mode is the same for all specified devices. If different settings are desired, this function can be invoked multiple times with a different set of parameters. A PHONE_STATE message is sent to the application after the hookswitch state has changed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY, PHONE_STATE


phoneSetLamp

The phoneSetLamp function causes the specified lamp to be lit on the specified open phone device in the specified lamp mode.

LONG WINAPI phoneSetLamp(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  DWORD dwLampMode
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwButtonLampID
The button whose lamp is to be lit.
dwLampMode
How the lamp is to be lit. This parameter uses one and only one of the PHONELAMPMODE_ Constants.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALLAMPMODE, PHONEERR_UNINITIALIZED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY


phoneSetRing

The phoneSetRing function rings the specified open phone device using the specified ring mode and volume.

LONG WINAPI phoneSetRing(
  HPHONE hPhone,
  DWORD dwRingMode,
  DWORD dwVolume
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone device.
dwRingMode
The ringing pattern with which to ring the phone. This parameter must be within the range of zero to the value of the dwNumRingModes member in the PHONECAPS structure. If dwNumRingModes is zero, the ring mode of the phone cannot be controlled; if dwNumRingModes is 1, a value of 0 for dwRingMode indicates that the phone should not be rung (silence), and other values from 1 to dwNumRingModes are valid ring modes for the phone device.
dwVolume
The volume level with which the phone is ringing. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALRINGMODE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY, PHONECAPS


phoneSetStatusMessages

The phoneSetStatusMessages function enables an application to monitor the specified phone device for selected status events.

LONG WINAPI phoneSetStatusMessages(
  HPHONE hPhone,
  DWORD dwPhoneStates,
  DWORD dwButtonModes,
  DWORD dwButtonStates
);

Parameters

hPhone
A handle to the open phone device to be monitored.
dwPhoneStates
These flags specify the set of phone status changes and events for which the application can receive notification messages. This parameter can have zero, one, or more of the PHONESTATE_ Constants.
dwButtonModes
The set of phone-button modes for which the application can receive notification messages. This parameter can have zero, one, or more of the PHONEBUTTONMODE_ Constants.
dwButtonStates
The set of phone-button state changes for which the application can receive notification messages. If the dwButtonModes parameter is zero, dwButtonStates is ignored. If dwButtonModes has one or more bits set, this parameter must also have at least one bit set. This parameter uses the PHONEBUTTONSTATE_ Constants.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONSTATE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

An application can use the phoneSetStatusMessages function to enable or disable the generation of the corresponding messages. All phone status messages are disabled by default.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneInitialize, phoneInitializeEx, phoneOpen


phoneSetVolume

The phoneSetVolume function sets the volume of the speaker component of the specified hookswitch device to the specified level.

LONG WINAPI phoneSetVolume(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  DWORD dwVolume
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwHookSwitchDev
The hookswitch device whose speaker's volume is to be set, one of the PHONEHOOKSWITCHDEV_ Constants.
dwVolume
The new volume setting of the device. The dwVolume parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.

See Also

TAPI 2.2 Reference Overview, Supplementary Phone Service Functions, PHONE_REPLY


phoneShutdown

The phoneShutdown function shuts down the application's usage of TAPI's phone abstraction.

LONG WINAPI phoneShutdown(
  HPHONEAPP hPhoneApp
);

Parameters

hPhoneApp
The application's usage handle for TAPI.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_NOMEM, PHONEERR_UNINITIALIZED, PHONEERR_RESOURCEUNAVAIL.

Remarks

If this function is called when the application has open phone devices, these devices are closed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.


TAPI Structures

This section contains the reference for the following Telephony Application Programming Interface (TAPI) structures:

Call Center Structures

Line Device Structures

Phone Device Structures


Call Center Structures

This section is an alphabetic listing for TAPI call center structures.

LINEAGENTACTIVITYENTRY

LINEAGENTACTIVITYLIST

LINEAGENTCAPS

LINEAGENTENTRY

LINEAGENTGROUPENTRY

LINEAGENTGROUPLIST

LINEAGENTINFO

LINEAGENTLIST

LINEAGENTSESSIONENTRY

LINEAGENTSESSIONINFO

LINEAGENTSESSIONLIST

LINEAGENTSTATUS

LINEPROXYREQUEST

LINEPROXYREQUESTLIST

LINEQUEUEENTRY

LINEQUEUEINFO

LINEQUEUELIST


LINEAGENTACTIVITYENTRY

The LINEAGENTACTIVITYENTRY structure describes a single ACD agent activity. The LINEAGENTACTIVITYLIST structure can contain an array of LINEAGENTACTIVITYENTRY structures.

typedef struct lineagentactivityentry_tag {
  DWORD  dwID;
  DWORD  dwNameSize;
  DWORD  dwNameOffset;
} LINEAGENTACTIVITYENTRY, *LPLINEAGENTACTIVITYENTRY;

Members

dwID
A unique identifier for an activity. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwNameSize
dwNameOffset
Size, in bytes, and offset from the beginning of the containing structure of a null-terminated string specifying the name and other identifying information of an activity that can be selected by calling the lineSetAgentActivity function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEPROXYREQUEST, LINEAGENTACTIVITYLIST, lineGetAgentActivityList, lineSetAgentActivity


LINEAGENTACTIVITYLIST

The LINEAGENTACTIVITYLIST structure describes a list of ACD agent activities.This structure can contain an array of LINEAGENTACTIVITYENTRY structures. The lineGetAgentActivityList function returns the LINEAGENTACTIVITYLIST structure.

typedef struct lineagentactivitylist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwNumEntries;
  DWORD  dwListSize;
  DWORD  dwListOffset;
} LINEAGENTACTIVITYLIST, *LPLINEAGENTACTIVITYLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumEntries
The number of LINEAGENTACTIVITYENTRY structures that appear in the List array. The value is 0 if no agent activity codes are available.
dwListSize
dwListOffset
Total size, in bytes, and offset from the beginning of LINEAGENTACTIVITYLIST of an array of LINEAGENTACTIVITYENTRY elements indicating information about activity that could be specified for the current logged-in agent. This is dwNumEntries times SIZEOF(LINEAGENTACTIVITYENTRY).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEAGENTACTIVITYENTRY, lineGetAgentActivityList, lineSetAgentActivity


LINEAGENTCAPS

The LINEAGENTCAPS structure describes the capabilities of an ACD agent. The lineGetAgentCaps function returns the LINEAGENTCAPS structure.

typedef struct lineagentcaps_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwAgentHandlerInfoSize;
  DWORD  dwAgentHandlerInfoOffset;
  DWORD  dwCapsVersion;

  DWORD  dwFeatures;
  DWORD  dwStates;
  DWORD  dwNextStates;
  DWORD  dwMaxNumGroupEntries;
  DWORD  dwAgentStatusMessages;

  DWORD  dwNumAgentExtensionIDs;
  DWORD  dwAgentExtensionIDListSize;
  DWORD  dwAgentExtensionIDListOffset;
  GUID   ProxyGUID;   //TAPI Version 2.2
} LINEAGENTCAPS, *LPLINEAGENTCAPS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwAgentHandlerInfoSize
dwAgentHandlerInfoOffset
The size, in bytes, and offset from the beginning of LINEAGENTCAPS of a null-terminated string specifying the name, version, or other identifying information of the server application that is handling agent requests.
dwCapsVersion
The TAPI version that the agent handler application used in preparing the contents of this structure. This is no greater than the API version that the calling application passed in to lineGetAgentCaps.
dwFeatures
The agent-related features available for this line using the LINEAGENTFEATURE_ constants. Invoking a supported feature requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This field allows an application to discover which agent features can be (and which can never be) supported by the device.
dwStates
The LINEAGENTSTATE_ constants that can be used in the dwAgentState parameter of lineSetAgentState. Setting a supported state requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding state is never available. A one indicates that the corresponding state may be available if the line is in the appropriate state for the state to be meaningful. This field allows an application to discover which agent states can be (and which can never be) supported on the device.
dwNextStates
The LINEAGENTSTATE_ constants that can be used in the dwNextAgentState parameter of lineSetAgentState. Setting a supported state requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding state is never available. A one indicates that the corresponding state may be available if the line is in the appropriate state for the state to be meaningful. This field allows an application to discover which agent states can be (and which can never be) supported on the device.
dwMaxNumGroupEntries
The maximum number of agent identifiers that can be logged in on the address simultaneously. Determines the highest value that can be passed in as the dwNumEntries member in the LINEAGENTGROUPLIST structure to lineSetAgentGroup.
dwAgentStatusMessages
Indicates the LINEAGENTSTATUS_ constants that can be received by the application in dwParam2 of a LINE_AGENTSTATUS message.
dwNumAgentExtensionIDs
The number of LINEEXTENSIONID structures that appear in the ExtensionIDList array. The value is 0 if agent-handler-specific extensions are supported on the address.
dwAgentExtensionIDListSize
dwAgentExtensionIDListOffset
Total size, in bytes, and offset from the beginning of LINEAGENTCAPS of an array of LINEEXTENSIONID elements. The size is dwNumExtensionIDs times SIZEOF(LINEEXTENSIONID). The array lists the 128-bit universally unique identifiers for all agent-handler-specific extensions supported by the agent handle for the address. The extension being used is referenced in the lineAgentSpecific function and LINE_AGENTSPECIFIC message by its position in this table, the first entry being entry 0, so it is important that the agent handler always present extension identifiers in this array in the same order.
ProxyGUID
GUID for ACD proxy associated with the line. This element is exposed only to applications that negotiate a TAPI version of 2.2 or higher.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_AGENTSPECIFIC, LINE_AGENTSTATUS, LINEAGENTGROUPLIST, lineAgentSpecific, LINEEXTENSIONID, lineGetAgentCaps, LINEPROXYREQUEST, lineSetAgentGroup, lineSetAgentState


LINEAGENTENTRY

The LINEAGENTENTRY structure describes an individual ACD agent. The LINEAGENTLIST structure can contain an array of LINEAGENTENTRY structures.

typedef struct lineagententry_tag{
  HAGENT  hAgent;
  DWORD  dwNameSize;
  DWORD  dwNameOffset;
  DWORD  dwIDSize;
  DWORD  dwIDOffset;
  DWORD  dwPINSize;
  DWORD  dwPINOffset;
} LINEAGENTENTRY, *LPLINEAGENTENTRY;

Members

hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of these identifiers.
dwNameSize
dwNameOffset
The size, in bytes, and offset from the beginning of the structure of a null-terminated string that specifies the name of the agent, which is also the operating system's user name.
dwIDSize
dwIDOffset
The size, in bytes, and offset from the beginning of the structure of a null-terminated string that specifies the ID of the agent. Used by legacy ACD systems to identify the agent.
dwPINSize
dwPINOffset
The size, in bytes, and offset from the beginning of the structure of a null-terminated string that specifies the PIN or password of the agent. Used by legacy ACD systems for agent authorization.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTLIST


LINEAGENTGROUPENTRY

The LINEAGENTGROUPENTRY structure provides information on ACD agent groups. The LINEAGENTGROUPLIST structure can contain an array of LINEAGENTGROUPENTRY structures.

typedef struct lineagentgroupentry_tag {
 struct {
  DWORD  dwGroupID1;
  DWORD  dwGroupID2;
  DWORD  dwGroupID3;
  DWORD  dwGroupID4;
 } GroupID;
  DWORD  dwNameSize;
  DWORD  dwNameOffset;
} LINEAGENTGROUPENTRY, *LPLINEAGENTGROUPENTRY;

Members

dwGroupID1
dwGroupID2
dwGroupID3
dwGroupID4
This set of four DWORDs is a universally unique identifier for a group. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwNameSize
dwNameOffset
Size, in bytes, and offset from the beginning of the containing structure of a null-terminated string specifying the name and other identifying information of an ACD group or queue into which the agent can log in. This string can contain such information as supervisor and skill level, to assist the agent in selecting the correct group from a list displayed on their workstation screen.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEAGENTGROUPLIST, lineGetAgentGroupList, lineGetGroupList, lineSetAgentGroup


LINEAGENTGROUPLIST

The LINEAGENTGROUPLIST structure describes a list of ACD agent groups. This structure can contain an array of LINEAGENTGROUPENTRY structures.

Multiple functions use the LINEAGENTGROUPLIST structure; these include the lineGetAgentGroupList, lineGetGroupList and lineSetAgentGroup functions.

typedef struct lineagentgrouplist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwNumEntries;
  DWORD  dwListSize;
  DWORD  dwListOffset;
} LINEAGENTGROUPLIST, *LPLINEAGENTGROUPLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumEntries
The number of LINEAGENTGROUPENTRY structures that appear in the List array. The value is 0 if no agent is to be logged in on the address.
dwListSize
dwListOffset
Total size, in bytes, and offset from the beginning of LINEAGENTGROUPLIST of an array of LINEAGENTGROUPENTRY elements specifying information about each group into which the current agent is to be logged in at the address. This is dwNumEntries times SIZEOF(LINEAGENTGROUPENTRY).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEAGENTGROUPENTRY, lineGetAgentGroupList, lineGetGroupList, lineSetAgentGroup


LINEAGENTINFO

The LINEAGENTINFO structure contains information about an ACD agent. The lineGetAgentInfo function returns the LINEAGENTINFO structure.

typedef struct lineagentinfo_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwAgentState;
  DWORD  dwNextAgentState;
  DWORD  dwMeasurementPeriod;
  CURRENCY  cyOverallCallRate;
  DWORD  dwNumberOfACDCalls;
  DWORD  dwNumberOfIncomingCalls;
  DWORD  dwNumberOfOutgoingCalls;
  DWORD  dwTotalACDTalkTime;
  DWORD  dwTotalACDCallTime;
  DWORD  dwTotalACDWrapUpTime;

} LINEAGENTINFO, *LPLINEAGENTINFO;

Members

dwTotalSize
The total size, in bytes, allocated to this structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this structure that contains useful information.
dwAgentState
dwNextAgentState
Must be one of the LINEAGENTSTATEEX_ constants.
dwMeasurementPeriod
The period (in seconds) for which the switch or implementation stores and calculates information. For example, dwNumberOfACDCalls holds the number of calls the agent handled; dwMeasurementPeriod indicates if this value referenced the calls handed in the last hour, day, or month.
cyOverallCallRate
The agent's call rate (calls per agent hour—where agent hour represents the time that an agent was active in one or more agent sessions) across all agent sessions. This is a fixed-point decimal number.
dwNumberOfACDCalls
The number of ACD calls handled by this agent across all sessions.
dwNumberOfIncomingCalls
The number of incoming non-ACD calls handled by this agent.
dwNumberOfOutgoingCalls
The number of outgoing non-ACD calls handled by this agent.
dwTotalACDTalkTime
The number of seconds spent talking in ACD calls by this agent across all sessions.
dwTotalACDCallTime
The number of seconds spent on ACD calls by this agent (across all sessions). Includes the time on phone plus wrap-up time.
dwTotalACDWrapUpTime
The number of seconds spent on ACD call wrap-up (after call work) by this agent across all sessions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineGetAgentInfo


LINEAGENTLIST

The LINEAGENTLIST structure describes a list of ACD agents. This structure can contain an array of LINEAGENTENTRY structures.

typedef struct lineagentlist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwNumEntries;
  DWORD  dwListSize;
  DWORD  dwListOffset;

} LINEAGENTLIST, *LPLINEAGENTLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this structure that contains useful information.
dwNumEntries
The number of LINEAGENTENTRY structures that appear in the list array. The value is zero if no agents are available.
dwListSize
dwListOffset
The total size, in bytes, and offset from the beginning of the structure of an array of LINEAGENTENTRY elements indicating information about agents. The dwListOffset member is dwNumEntries times SIZEOF(LINEAGENTENTRY).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTENTRY


LINEAGENTSESSIONENTRY

The LINEAGENTSESSIONENTRY structure describes an ACD agent session. The LINEAGENTSESSIONLIST structure can contain an array of LINEAGENTSESSIONENTRY structures.

typedef struct lineagentsessionentry_tag {
  HAGENTSESSION  hAgentSession;
  HAGENT  hAgent;
  GUID  GroupID;
  DWORD  dwWorkingAddressID;

} LINEAGENTSESSIONENTRY  , *LPLINEAGENTSESSIONENTRY;

Members

hAgentSession
A unique identifier for an agent session. It is the responsibility of the agent handler to generate and maintain uniqueness of these identifiers.
hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of these identifiers.
GroupID
A universally unique identifier for an ACD group. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwWorkingAddressID
The identifier of the address on which the agent will receive calls for this session.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTSESSIONLIST, lineGetAgentSessionList


LINEAGENTSESSIONINFO

The LINEAGENTSESSIONINFO structure contains information about the ACD agent session. The lineGetAgentSessionInfo function returns the LINEAGENTSESSIONINFO structure.

typedef struct lineagentsessioninfo_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwAgentSessionState;
  DWORD  dwNextAgentSessionState;
  DATE   dateSessionStartTime;
  DWORD  dwSessionDuration;
  DWORD  dwNumberOfCalls;
  DWORD  dwTotalTalkTime;
  DWORD  dwAverageTalkTime;
  DWORD  dwTotalCallTime;
  DWORD  dwAverageCallTime;
  DWORD  dwTotalWrapUpTime;
  DWORD  dwAverageWrapUpTime;
  CURRENCY  cyACDCallRate;
  DWORD  dwLongestTimeToAnswer;
  DWORD  dwAverageTimeToAnswer;

} LINEAGENTSESSIONINFO, *LPLINEAGENTSESSIONINFO;

Members

dwTotalSize
The total size, in bytes, allocated to this structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this structure that contains useful information.
dwAgentSessionState
dwNextAgentSessionState
These members use LINEAGENTSESSIONSTATE_ constants.
dateSessionStartTime
Time session was created.
dwSessionDuration
The duration of the agent session in seconds. Active period only; timing stops when a session enters the ASST_SESSION_ENDED state.
dwNumberOfCalls
The number of ACD calls handled during this agent session by this agent.
dwTotalTalkTime
The number of seconds spent talking in ACD calls during this agent session by this agent.
dwAverageTalkTime
The average time (in seconds) spent talking for each ACD call, during this agent session by this agent.
dwTotalCallTime
The number of seconds spent on ACD calls during this agent session by this agent. It includes time on the phone plus wrap-up time.
dwAverageCallTime
The average time (in seconds) spent for each ACD call during this agent session. Includes time on the phone plus wrap-up time.
dwTotalWrapUpTime
The number of seconds spent on ACD call wrap-up (after-call work) during this agent session by this agent.
dwAverageWrapUpTime
The average time (in seconds) for each ACD call spent in wrap-up (after-call work) during this agent session
cyACDCallRate
The call rate for each agent session. This is a fixed-point decimal number.
dwLongestTimeToAnswer
The longest time (in seconds) a call was waiting to be answered.
dwAverageTimeToAnswer
The average time (in seconds) calls waited to be answered.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineGetAgentSessionInfo


LINEAGENTSESSIONLIST

The LINEAGENTSESSIONLIST structure describes a list of ACD agent sessions. This structure can contain an array of LINEAGENTSESSIONENTRY structures. The lineGetAgentSessionList function returns the LINEAGENTSESSIONLIST structure.

typedef struct lineagentsessionlist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwNumEntries;
  DWORD  dwListSize;
  DWORD  dwListOffset;

} LINEAGENTSESSIONLIST, *LPLINEAGENTSESSIONLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this structure that contains useful information.
dwNumEntries
The number of LINEAGENTSESSIONENTRY structures that appear in the list array. The value is zero if no agent sessions have been created.
dwListSize
dwListOffset
The total size, in bytes, and offset from the beginning of LINEAGENTSESSIONLIST of an array of LINEAGENTSESSIONENTRY elements indicating information about agents. The dwListOffset member is dwNumEntries times SIZEOF(LINEAGENTSESSIONENTRY).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, LINEAGENTSESSIONENTRY, lineGetAgentSessionList


LINEAGENTSTATUS

The LINEAGENTSTATUS structure describes the current status of an ACD agent. The lineGetAgentStatus function returns the LINEAGENTSTATUS structure.

typedef struct lineagentstatus_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwNumEntries;
  DWORD  dwGroupListSize;
  DWORD  dwGroupListOffset;

  DWORD  dwState;
  DWORD  dwNextState;
  DWORD  dwActivityID;
  DWORD  dwActivitySize;
  DWORD  dwActivityOffset;

  DWORD  dwAgentFeatures;
  DWORD  dwValidStates;
  DWORD  dwValidNextStates;
} LINEAGENTSTATUS, *LPLINEAGENTSTATUS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumEntries
The number of LINEAGENTGROUPENTRY structures that appear in the GroupList array. The value is 0 if no agent is logged in on the address.
dwGroupListSize
dwGroupListOffset
Total size, in bytes, and offset from the beginning of LINEAGENTSTATUS of an array of LINEAGENTGROUPENTRY elements. The size is dwNumEntries times SIZEOF(LINEAGENTGROUPENTRY). The array contains groups into which the agent is currently logged in on the address.
dwState
The current state of the agent. One of the LINEAGENTSTATE_ constants.
dwNextState
The state into which the agent is automatically placed when the current call completes. One of the LINEAGENTSTATE_ constants.
dwActivityID
The identifier of the current agent activity.
dwActivitySize
dwActivityOffset
Size, in bytes, and offset from the beginning of LINEAGENTSTATUS of a null-terminated string specifying the current agent activity.
dwAgentFeatures
The agent-related features available at the time the status was obtained, using the LINEAGENTFEATURE_ constants.
dwValidStates
The agent states that could be selected, at this point in time, using lineSetAgentState. Consists of one or more of the LINEAGENTSTATE_ constants.
dwValidNextStates
The next agent states that could be selected, at this point in time, by calling the lineSetAgentState function. Consists of one or more of the LINEAGENTSTATE_ constants.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEAGENTGROUPENTRY, lineGetAgentStatus


LINEPROXYREQUEST

The LINEPROXYREQUEST structure contains parameter values of the application making the proxy request. Multiple TAPI call center functions generate a LINE_PROXYREQUEST message that references a LINEPROXYREQUEST structure.

typedef struct lineproxyrequest_tag {
  DWORD dwSize;
  DWORD dwClientMachineNameSize;
  DWORD dwClientMachineNameOffset;
  DWORD dwClientUserNameSize;
  DWORD dwClientUserNameOffset;
  DWORD dwClientAppAPIVersion;
  DWORD dwRequestType;
 union {
  struct {
  DWORD dwAddressID;
    LINEAGENTGROUPLIST GroupList;
    } SetAgentGroup;
  struct {
  DWORD dwAddressID;
  DWORD dwAgentState;
  DWORD dwNextAgentState;
    } SetAgentState;
  struct {
  DWORD dwAddressID;
  DWORD dwActivityID;
    } SetAgentActivity;
  struct {
  DWORD dwAddressID;
    LINEAGENTCAPS AgentCaps;
    } GetAgentCaps;
  struct {
  DWORD dwAddressID;
    LINEAGENTSTATUS AgentStatus;
    } GetAgentStatus;
  struct {
  DWORD dwAddressID;
  DWORD dwAgentExtensionIDIndex;
  DWORD dwSize;
    BYTE Params[1];
    } AgentSpecific;
  struct {
  DWORD dwAddressID;
    LINEAGENTACTIVITYLIST ActivityList;
    } GetAgentActivityList;
  struct {
  DWORD dwAddressID;
    LINEAGENTGROUPLIST GroupList;
    } GetAgentGroupList;
  struct {
  HAGENT  hAgent; // TAPI v3.0
   DWORD  dwAgentIDSize; // TAPI v3.0
   DWORD  dwAgentIDOffset; // TAPI v3.0
   DWORD  dwAgentPINSize; // TAPI v3.0
   DWORD  dwAgentPINOffset;
    } CreateAgent;
  struct {
  HAGENT  hAgent; // TAPI v3.0
   DWORD  dwAgentState; // TAPI v3.0
   DWORD  dwNextAgentState; // TAPI v3.0
    } SetAgentStateEx;
  struct {
  HAGENT  hAgent; // TAPI v3.0
   DWORD  dwMeasurementPeriod; // TAPI v3.0
    } SetAgentMeasurementPeriod;
  struct {
  HAGENT  hAgent; // TAPI v3.0
  LINEAGENTINFO  AgentInfo; // TAPI v3.0
    } GetAgentInfo;
  struct {
  HAGENTSESSION  hAgentSession; // TAPI v3.0
   DWORD  dwAgentPINSize;
   DWORD  dwAgentPINOffset;
  HAGENT  hAgent; // TAPI v3.0
    GUID  GroupID; // TAPI v3.0
    DWORD  dwWorkingAddressID; // TAPI v3.0
    } CreateAgentSession;
  struct {
  HAGENT  hAgent; // TAPI v3.0
    LINEAGENTSESSIONLIST  SessionList; // TAPI v3.0
    } GetAgentSessionList;
  struct {
  HAGENTSESSION  hAgentSession; // TAPI v3.0
    LINEAGENTSESSIONINFO  SessionInfo; // TAPI v3.0
    } GetAgentSessionInfo;
  struct {
  HAGENTSESSION  hAgentSession; // TAPI v3.0
  DWORD  dwAgentSessionState; // TAPI v3.0
  DWORD  dwNextAgentSessionState; // TAPI v3.0
    } SetAgentSessionState;
  struct {
    GUID  GroupID; // TAPI v3.0
    LINEQUEUELIST  QueueList; // TAPI v3.0
    } GetQueueList;
  struct {
  DWORD  dwQueueID; // TAPI v3.0
  DWORD  dwMeasurementPeriod; // TAPI v3.0
    } SetQueueMeasurementPeriod;
  struct {
  DWORD  dwQueueID; // TAPI v3.0
    LINEQUEUEINFO  QueueInfo; // TAPI v3.0
    } GetQueueInfo;
  struct {
    LINEAGENTGROUPLIST  GroupList; // TAPI v3.0
    } GetGroupList;

  };
} LINEPROXYREQUEST, *LPLINEPROXYREQUEST;

Members

dwSize
The total number of bytes allocated by TAPI to contain the LINEPROXYREQUEST structure. The dwTotalSize member of any structure contained within LINEPROXYREQUEST (for example, LINEAGENTCAPS) reflects only the number of bytes allocated for that specific structure.
dwClientMachineNameSize
dwClientMachineNameOffset
Size, in bytes, (including the terminating NULL) and offset from the beginning of LINEPROXYREQUEST of a null-terminated string identifying the client machine that made this request.
dwClientUserNameSize
dwClientUserNameOffset
Size, in bytes, (including the terminating NULL) and offset from the beginning of LINEPROXYREQUEST of a null-terminated string identifying the user under whose account the application is running on the client machine.
dwClientAppAPIVersion
The global (highest) API version supported by the application that made the request. The proxy handler should restrict the contents of any data returned to the application to those members and values that were defined in this, or earlier, versions of TAPI.
dwRequestType
One of the LINEPROXYREQUEST_ Constants. Identifies the type of function and the union component that defines the remaining data in the structure.
SetAgentGroup
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENT.
dwAddressID
The identifier of the address for which the agent is to be set.
GroupList
A structure of type LINEAGENTGROUPLIST. Offsets within this structure are relative to the beginning of SetAgentGroup.GroupList rather than to the beginning of the LINEPROXYREQUEST structure.
SetAgentState
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTSTATE.
dwAddressID
The identifier of the address for which the agent state is to be set.
dwAgentState
The new agent state, or zero to leave the agent state unchanged.
dwNextAgentState
The new next agent state, or zero to use the default next state associated with the specified agent state.
SetAgentActivity
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTACTIVITY.
dwAddressID
The identifier of the address for which the agent activity is to be set.
dwActivityID
The identifier for the activity being selected.
GetAgentCaps
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTCAPS.
dwAddressID
The identifier of the address for which the agent capabilities are to be retrieved.
AgentCaps
A structure of type LINEAGENTCAPS. Offsets within this structure are relative to the beginning of GetAgentCaps.AgentCaps rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.
GetAgentStatus
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTGROUP.
dwAddressID
The identifier of the address for which the agent status is to be retrieved.
AgentStatus
A structure of type LINEAGENTSTATUS. Offsets within this structure are relative to the beginning of GetAgentStatus.AgentStatus rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.
AgentSpecific
The union component used when dwRequestType is LINEPROXYREQUEST_AGENTSPECIFIC.
dwAddressID
The identifier of the address for which the agent status is to be retrieved.
dwAgentExtensionIDIndex
The index of the handler extension being invoked; the identifier's position within the array of extension identifiers returned in LINEAGENTCAPS.
dwSize
The total size, in bytes, of the Params parameter block.
Params
A block of memory that includes the contents passed to the handler from the application. If the handler is to return data to the application, it must be written into this parameter block before calling lineProxyResponse.
GetAgentActivityList
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTACTIVITYLIST.
dwAddressID
The identifier of the address for which the agent activity list is to be retrieved.
ActivityList
A structure of type LINEAGENTACTIVITYLIST. Offsets within this structure are relative to the beginning of GetAgentActivityList.ActivityList rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.
GetAgentGroupList
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTGROUPLIST.
dwAddressID
The identifier of the address for which the agent group list is to be retrieved.
GroupList
A structure of type LINEAGENTGROUPLIST. Offsets within this structure are relative to the beginning of GetAgentGroupList.GroupList rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.
CreateAgent
The union component used when dwRequestType is LINEPROXYREQUEST_CREATEAGENT.
hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwAgentIDSize
dwAgentIDOffset
The size, in bytes, and offset from the beginning of the structure of a null-terminated string that specifies the ID of the agent.
dwAgentPINSize
dwAgentPINOffset
The size, in bytes, and offset from the beginning of the structure of a null-terminated string that specifies the PIN or password of the agent.
SetAgentStateEx
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTSTATEEX.
hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwAgentState
dwNextAgentState
One of the LINEAGENTSTATEEX_ Constants.
SetAgentMeasurementPeriod
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTMEASUREMENTPERIOD.
hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwMeasurementPeriod
The period (in seconds) for which the switch or implementation stores and calculates information. For example, dwNumberOfACDCalls holds the number of calls the agent handled; dwMeasurementPeriod indicates if this value referenced the calls handed in the last hour, day, or month.
GetAgentInfo
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTINFO.
hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
AgentInfo
A structure of type LINEAGENTINFO.
CreateAgentSession
The union component used when dwRequestType is LINEPROXYREQUEST_CREATEAGENTSESSION.
hAgentSession
A unique identifier for an agent session.
dwAgentPINSize
dwAgentPINOffset
The size, in bytes, and offset from the beginning of the structure of a null-terminated string that specifies the PIN or password of the agent.
hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
GroupID
A universally unique identifier for an ACD group. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwWorkingAddressID
The identifier of the address on which the agent will receive calls for this session.
GetAgentSessionList
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTSESSIONLIST.
hAgent
A unique identifier for an agent. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
SessionList
A structure of type LINEAGENTSESSIONLIST.
GetAgentSessionInfo
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTSESSIONINFO.
hAgentSession
A unique identifier for an agent session. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
SessionInfo
A structure of type LINEAGENTSESSIONINFO.
SetAgentSessionState
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTSESSIONSTATE.
hAgentSession
A unique identifier for an agent session. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwAgentSessionState
dwNextAgentSessionState
These members use LINEAGENTSESSIONSTATE_ constants.
GetQueueList
The union component used when dwRequestType is LINEPROXYREQUEST_GETQUEUELIST.
GroupID
A universally unique identifier for an ACD group. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
QueueList
A structure of type LINEQUEUELIST.
SetQueueMeasurementPeriod
The union component used when dwRequestType is LINEPROXYREQUEST_SETQUEUEMEASUREMENTPERIOD.
dwQueueID
A unique identifier for a queue. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwMeasurementPeriod
The period (in seconds) for which the switch or implementation stores and calculates information.
GetQueueInfo
The union component used when dwRequestType is LINEPROXYREQUEST_GETQUEUEINFO.
dwQueueID
A unique identifier for a queue. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
QueueInfo
A structure of type LINEQUEUEINFO.
GetGroupList
The union component used when dwRequestType is LINEPROXYREQUEST_GETGROUPLIST.
GroupList
A structure of type LINEAGENTGROUPLIST.

Remarks

An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineProxyResponse, LINEAGENTCAPS, LINEAGENTGROUPLIST, LINEAGENTSTATUS, LINEAGENTACTIVITYLIST, LINEAGENTSESSIONLIST, LINEAGENTSESSIONINFO, LINEQUEUELIST, LINE_PROXYREQUEST


LINEPROXYREQUESTLIST

The LINEPROXYREQUESTLIST structure describes a list of proxy requests. The lineGetProxyStatus function returns the LINEPROXYREQUESTLIST structure.

typedef struct lineproxyrequestlist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwNumEntries;
  DWORD  dwListSize;
  DWORD  dwListOffset;

} LINEPROXYREQUESTLIST, *LPLINEPROXYREQUESTLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this structure that contains useful information.
dwNumEntries
The number of DWORD elements that appear in the list array.
dwListSize
dwListOffset
The total size, in bytes, and offset from the beginning of LINEPROXYREQUESTLIST of an array of DWORD elements indicating the currently supported proxy request types. Each element is one of the LINEPROXYREQUEST_ constants. The dwListOffset member is dwNumEntries times SIZEOF(DWORD).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, LINEPROXYREQUEST_ Constants, lineGetProxyStatus


LINEQUEUEENTRY

The LINEQUEUEENTRY structure provides the information for a single queue entry. The LINEQUEUELIST structure can contain an array of LINEQUEUEENTRY structures. This structure requires TAPI 3.0 version negotiation.

typedef struct linequeueentry_tag {
  DWORD  dwQueueID;
  DWORD  dwNameSize;
  DWORD  dwNameOffset;

} LINEQUEUEENTRY, *LPLINEQUEUEENTRY;

Members

dwQueueID
A unique identifier for a queue. It is the responsibility of the agent handler to generate and maintain uniqueness of this identifier.
dwNameSize
dwNameOffset
The size, in bytes, and offset from the beginning of the structure of a null-terminated string that specifies the name of the queue.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls LINEQUEUELIST, lineGetQueueList function


LINEQUEUEINFO

The LINEQUEUEINFO structure provides information about a queue on a line device. The lineGetQueueInfo function returns the LINEQUEUEINFO structure. This structure requires TAPI 3.0 version negotiation.

typedef struct linequeueinfo_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwMeasurementPeriod;
  DWORD  dwTotalCallsQueued;
  DWORD  dwCurrentCallsQueued;
  DWORD  dwTotalCallsAbandoned;
  DWORD  dwTotalCallsFlowedIn;
  DWORD  dwTotalCallsFlowedOut;
  DWORD  dwLongestEverWaitTime;
  DWORD  dwCurrentLongestWaitTime;
  DWORD  dwAverageWaitTime;
  DWORD  dwFinalDisposition;
} LINEQUEUEINFO, *LPLINEQUEUEINFO;

Members

dwTotalSize
The total size, in bytes, allocated to this structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this structure that contains useful information.
dwMeasurementPeriod
The period (in seconds) for which the switch or implementation stores and calculates information. For example, dwTotalCallsAbandoned holds the number of abandoned calls; dwMeasurementPeriod would indicate if this value referenced the calls queued in an hour, day, or month, for example.
dwTotalCallsQueued
The total number of incoming calls for this queue during this measurement period.
dwCurrentCallsQueued
The number of incoming calls currently waiting.
dwTotalCallsAbandoned
The number of abandoned calls during this measurement period.
dwTotalCallsFlowedIn
The total number of calls that flowed into this queue (passed down from another queue or ACD group) during this measurement period.
dwTotalCallsFlowedOut
The total number of calls that flowed out of this queue (passed down to another queue or ACD group) during this measurement period.
dwLongestEverWaitTime
The longest time, in seconds, any call has waited in queue.
dwCurrentLongestWaitTime
The longest time, in seconds, that a current call (that is, a call still in queue) has been waiting.
dwAverageWaitTime
The average time, in seconds, that a call has waited in queue.
dwFinalDisposition
The final disposition of the queue.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineGetQueueInfo


LINEQUEUELIST

The LINEQUEUELIST structure describes a list of queues. This structure can contain an array of LINEQUEUEENTRY structures. The lineGetQueueList function returns the LINEQUEUELIST structure. LINEQUEUELIST requires TAPI 3.0 version negotiation.

typedef struct linequeuelist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwNumEntries;
  DWORD  dwListSize;
  DWORD  dwListOffset;

} LINEQUEUELIST, *LPLINEQUEUELIST;

Members

dwTotalSize
The total size, in bytes, allocated to this structure.
dwNeededSize
The size, in bytes, needed to hold all the information requested.
dwUsedSize
The size, in bytes, of the portion of this structure that contains useful information.
dwNumEntries
The number of LINEQUEUEENTRY structures that appear in the list array. The value is zero if no queue is available.
dwListSize
dwListOffset
The total size, in bytes, and offset from the beginning of LINEQUEUELIST of an array of LINEQUEUEENTRY elements indicating information about agents. The dwListOffset member is dwNumEntries times SIZEOF(LINEQUEUEENTRY).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, LINEQUEUEENTRY, lineGetQueueList function


Line Device Structures

This section contains an alphabetic listing of the line device structures used by TAPI. These line device structures include:

  • LINEADDRESSCAPS
  • LINEADDRESSSTATUS
  • LINEAPPINFO
  • LINECALLHUBTRACKINGINFO
  • LINECALLINFO
  • LINECALLLIST
  • LINECALLPARAMS
  • LINECALLSTATUS
  • LINECALLTREATMENTENTRY
  • LINECARDENTRY
  • LINECOUNTRYENTRY
  • LINECOUNTRYLIST
  • LINEDEVCAPS
  • LINEDEVSTATUS
  • LINEDIALPARAMS
  • LINEEXTENSIONID
  • LINEFORWARD
  • LINEFORWARDLIST
  • LINEGENERATETONE
  • LINEINITIALIZEEXPARAMS
  • LINELOCATIONENTRY
  • LINEMEDIACONTROLCALLSTATE
  • LINEMEDIACONTROLDIGIT
  • LINEMEDIACONTROLMEDIA
  • LINEMEDIACONTROLTONE
  • LINEMESSAGE
  • LINEMONITORTONE
  • LINEPROVIDERENTRY
  • LINEPROVIDERLIST
  • LINEREQMEDIACALL
  • LINEREQMAKECALL
  • LINETERMCAPS
  • LINETRANSLATECAPS
  • LINETRANSLATEOUTPUT


LINEADDRESSCAPS

The LINEADDRESSCAPS structure describes the capabilities of a specified address. The lineGetAddressCaps function and the TSPI_lineGetAddressCaps function return the LINEADDRESSCAPS structure.

typedef struct lineaddresscaps_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwLineDeviceID;

  DWORD  dwAddressSize;
  DWORD  dwAddressOffset;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;

  DWORD  dwAddressSharing;
  DWORD  dwAddressStates;
  DWORD  dwCallInfoStates;
  DWORD  dwCallerIDFlags;
  DWORD  dwCalledIDFlags;
  DWORD  dwConnectedIDFlags;
  DWORD  dwRedirectionIDFlags;
  DWORD  dwRedirectingIDFlags;
  DWORD  dwCallStates;
  DWORD  dwDialToneModes;
  DWORD  dwBusyModes;
  DWORD  dwSpecialInfo;
  DWORD  dwDisconnectModes;

  DWORD  dwMaxNumActiveCalls;
  DWORD  dwMaxNumOnHoldCalls;
  DWORD  dwMaxNumOnHoldPendingCalls;
  DWORD  dwMaxNumConference;
  DWORD  dwMaxNumTransConf;

  DWORD  dwAddrCapFlags;
  DWORD  dwCallFeatures;
  DWORD  dwRemoveFromConfCaps;
  DWORD  dwRemoveFromConfState;
  DWORD  dwTransferModes;
  DWORD  dwParkModes;

  DWORD  dwForwardModes;
  DWORD  dwMaxForwardEntries;
  DWORD  dwMaxSpecificEntries;
  DWORD  dwMinFwdNumRings;
  DWORD  dwMaxFwdNumRings;

  DWORD  dwMaxCallCompletions;
  DWORD  dwCallCompletionConds;
  DWORD  dwCallCompletionModes;
  DWORD  dwNumCompletionMessages;
  DWORD  dwCompletionMsgTextEntrySize;
  DWORD  dwCompletionMsgTextSize;
  DWORD  dwCompletionMsgTextOffset;
  DWORD  dwAddressFeatures;

  DWORD  dwPredictiveAutoTransferStates;
  DWORD  dwNumCallTreatments;
  DWORD  dwCallTreatmentListSize;
  DWORD  dwCallTreatmentListOffset;
  DWORD  dwDeviceClassesSize;
  DWORD  dwDeviceClassesOffset;
  DWORD  dwMaxCallDataSize;
  DWORD  dwCallFeatures2;
  DWORD  dwMaxNoAnswerTimeout;
  DWORD  dwConnectedModes;
  DWORD  dwOfferingModes;
  DWORD  dwAvailableMediaModes;
} LINEADDRESSCAPS, FAR *LPLINEADDRESSCAPS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwLineDeviceID
The device identifier of the line device with which this address is associated.
dwAddressSize
dwAddressOffset
The size, in bytes, of the variably sized address field and the offset, in bytes, from the beginning of this data structure.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized device-specific field and the offset, in bytes, from the beginning of this data structure.
dwAddressSharing
The sharing mode of the address. This member can be one of the LINEADDRESSSHARING_ Constants.
dwAddressStates
Contains the address states changes for which the application may get notified in the LINE_ADDRESSSTATE message. This member uses one or more of the LINEADDRESSSTATE_ constants.
dwCallInfoStates
Describes the call information elements that are meaningful for all calls on this address. An application may get notified about changes in some of these states in LINE_CALLINFO messages. This member uses one or more of the LINECALLINFOSTATE_ constants.
dwCallerIDFlags
dwCalledIDFlags
dwConnectedIDFlags
dwRedirectionIDFlags
dwRedirectingIDFlags
Describes the various party identifier information types that can be provided for calls on this address. The caller is the originator of the session, "called" refers to the original destination, "redirection" is the new destination, and "redirecting" is the address which invoked redirection. These members uses one or more of the LINECALLPARTYID_ constants.
dwCallStates
Describes the various call states that can be reported for calls on this address. This member uses one or more of the LINECALLSTATE_ constants.
dwDialToneModes
Describes the various dial tone modes that can be reported for calls made on this address. This member is meaningful only if the dialtone call state can be reported. This member uses one or more of the LINEDIALTONEMODE_ constants.
dwBusyModes
Describes the various busy modes that can be reported for calls made on this address. This member is meaningful only if the busy call state can be reported. This member uses one or more of the LINEBUSYMODE_ constants.
dwSpecialInfo
Describes the various special information types that can be reported for calls made on this address. This member is meaningful only if the specialInfo call state can be reported. This member uses one or more of the LINESPECIALINFO_ constants.
dwDisconnectModes
Describes the various disconnect modes that can be reported for calls made on this address. This member is meaningful only if the disconnected call state can be reported. This member uses one or more of the LINEDISCONNECTMODE_ constants.
dwMaxNumActiveCalls
Contains the maximum number of active call appearances that the address can handle. This number does not include calls on hold or calls on hold pending transfer or conference.
dwMaxNumOnHoldCalls
Contains the maximum number of call appearances at the address that can be on hold.
dwMaxNumOnHoldPendingCalls
Contains the maximum number of call appearances at the address that can be on hold pending transfer or conference.
dwMaxNumConference
Contains the maximum number of parties that can join a single conference call on this address.
dwMaxNumTransConf
Specifies the number of parties (including "self") that can be added in a conference call that is initiated as a generic consultation call using lineSetupTransfer.
dwAddrCapFlags
Contains a series of packed bit flags that describe a variety of address capabilities. This member uses one or more of the LINEADDRCAPFLAGS_ constants.
dwCallFeatures
Specifies the switching capabilities or features available for all calls on this address using the LINECALLFEATURE_ Constants. This member represents the call-related features that may possibly be available on an address (static availability as opposed to dynamic availability). Invoking a supported feature requires the call to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the application has the right privileges to the call and the call is in the appropriate state for the operation to be meaningful. This member allows an application to discover which call features can be (and which can never be) supported by the address.
dwRemoveFromConfCaps
Specifies the address's capabilities for removing calls from a conference call. This member uses one of the LINEREMOVEFROMCONF_ constants.
dwRemoveFromConfState
Uses the LINECALLSTATE_ constants to specify the state of the call after it has been removed from a conference call.
dwTransferModes
Specifies the address's capabilities for resolving transfer requests. This member uses one of the LINETRANSFERMODE_ constants.
dwParkModes
Specifies the different call park modes available at this address. This member uses one of the LINEPARKMODE_ constants.
dwForwardModes
Specifies the different modes of forwarding available for this address. This member uses the LINEFORWARDMODE_ constants.
dwMaxForwardEntries
Specifies the maximum number of entries that can be passed to lineForward in the lpForwardList parameter.
dwMaxSpecificEntries
Specifies the maximum number of entries in the lpForwardList parameter passed to lineForward that can contain forwarding instructions based on a specific caller ID (selective call forwarding). This member is zero if selective call forwarding is not supported.
dwMinFwdNumRings
Specifies the minimum number of rings that can be set to determine when a call is officially considered "no answer."
dwMaxFwdNumRings
Specifies the maximum number of rings that can be set to determine when a call is officially considered "no answer." If this number of rings cannot be set, then dwMinFwdNumRings and dwMaxNumRings are equal.
dwMaxCallCompletions
Specifies the maximum number of concurrent call completion requests that can be outstanding on this line device. Zero implies that call completion is not available.
dwCallCompletionConds
Specifies the different call conditions under which call completion can be requested. This member uses one or more of the LINECALLCOMPLCOND_ constants.
dwCallCompletionModes
Specifies the way in which the call can be completed. This member uses one of the LINECALLCOMPLMODE_ constants.
dwNumCompletionMessages
Specifies the number of call completion messages that can be selected from when using the LINECALLCOMPLMODE_MESSAGE option. Individual messages are identified by values in the range zero through one less than dwNumCompletionMessages.
dwCompletionMsgTextEntrySize
Specifies the size, in bytes, of each of the call completion text descriptions pointed at by dwCompletionMsgTextSize and dwCompletionMsgTextOffset.
dwCompletionMsgTextSize
dwCompletionMsgTextOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field containing descriptive text about each of the call completion messages. Each message is dwCompletionMsgTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.
dwAddressFeatures
Specifies the features available for this address using the LINEADDRFEATURE_ Constants. Invoking a supported feature requires the address to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the address is in the appropriate state for the operation to be meaningful. This member allows an application to discover which address features can be (and which can never be) supported by the address.
dwPredictiveAutoTransferStates
The call state or states upon which a call made by a predictive dialer can be set to automatically transfer the call to another address; one or more of the LINECALLSTATE_ Constants. The value 0 indicates automatic transfer based on call state is unavailable.
dwNumCallTreatments
The number of entries in the array of LINECALLTREATMENTENTRY structures delimited by dwCallTreatmentListSize and dwCallTreatmentListOffset.
dwCallTreatmentListSize
dwCallTreatmentListOffset
The total size, in bytes, and offset from the beginning of LINEADDRESSCAPS of an array of LINECALLTREATMENTENTRY structures, indicating the call treatments supported on the address (that can be selected using lineSetCallTreatment). The value is dwNumCallTreatments times SIZEOF(LINECALLTREATMENTENTRY).
dwDeviceClassesSize
dwDeviceClassesOffset
Length in bytes and offset from the beginning of LINEADDRESSCAPS of a string consisting of the device class identifiers supported on this address for use with lineGetID, separated by NULLs; the last class indentifier is followed by two NULLs.
dwMaxCallDataSize
The maximum number of bytes that an application can set in LINECALLINFO using lineSetCallData.
dwCallFeatures2
Specifies additional switching capabilities or features available for all calls on this address using the LINECALLFEATURE2_ Constants. It is an extension of the dwCallFeatures member.
dwMaxNoAnswerTimeout
The maximum value in seconds that can be set in the dwNoAnswerTimeout member in LINECALLPARAMS when making a call. A value of 0 indicates that automatic abandonment of unanswered calls is not supported by the service provider, or that the timeout value is not adjustable by applications.
dwConnectedModes
Specifies the LINECONNECTEDMODE_ values that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.
dwOfferingModes
Specifies the LINEOFFERINGMODE_ values that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.
dwAvailableMediaModes
Indicates the media types (modes) that can be invoked on new calls created on this address, when the dwAddressFeatures member indicates that new calls are possible. If this member is zero, it indicates that the service provider either does not know or cannot indicate which media types are available, in which case any or all of the media types indicated in the dwMediaModes member in LINEDEVCAPS may be available.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications are compiled without this member in the LINEADDRESSCAPS structure, and using a SIZEOF(LINEADDRESSCAPS) smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetAddressCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize member less than the size of the fixed portion of the structure as defined in the dwAPIVersion member specified, LINEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetAddressCaps, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.

New service providers (that support the new API version) must examine the API version passed in. If the API version is less than the highest version supported by the provider, the service provider must not fill in fields not supported in older API versions, as these would fall in the variable portion of the older structure.

New applications must be cognizant of the API version negotiated, and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

The members dwPredictiveAutoTransferStates through dwAvailableMediaModes are available only to applications that request an API version of 2.0 or later when calling lineGetAddressCaps.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINE_ADDRESSSTATE, LINE_CALLINFO, LINE_CALLSTATE, LINE_LINEDEVSTATE, LINEADDRESSSTATUS, LINECALLINFO, LINECALLPARAMS, LINECALLSTATUS, LINECALLTREATMENTENTRY, LINEDEVCAPS, LINEDIALPARAMS, lineCompleteCall, lineForward, lineGenerateDigits, lineGetAddressCaps, TSPI_lineGetAddressCaps, lineGetID, lineSetCallData, lineSetCallTreatment


LINEADDRESSSTATUS

The LINEADDRESSSTATUS structure describes the current status of an address. The lineGetAddressStatus function and the TSPI_lineGetAddressStatus function return the LINEADDRESSSTATUS structure.

typedef struct lineaddressstatus_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwNumInUse;
  DWORD  dwNumActiveCalls;
  DWORD  dwNumOnHoldCalls;
  DWORD  dwNumOnHoldPendCalls;

  DWORD  dwAddressFeatures;
  DWORD  dwNumRingsNoAnswer;

  DWORD  dwForwardNumEntries;
  DWORD  dwForwardSize;
  DWORD  dwForwardOffset;

  DWORD  dwTerminalModesSize;
  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;
} LINEADDRESSSTATUS, FAR *LPLINEADDRESSSTATUS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumInUse
Specifies the number of stations that are currently using the address.
dwNumActiveCalls
The number of calls on the address that are in call states other than idle, onhold, onholdpendingtransfer, and onholdpendingconference.
dwNumOnHoldCalls
The number of calls on the address in the onhold state.
dwNumOnHoldPendCalls
The number of calls on the address in the onholdpendingtransfer or onholdpendingconference state.
dwAddressFeatures
Specifies the address-related API functions that can be invoked on the address in its current state. This member uses one or more of the LINEADDRFEATURE_ constants.
dwNumRingsNoAnswer
The number of rings set for this address before an unanswered call is considered as no answer.
dwForwardNumEntries
The number of entries in the array referred to by dwForwardSize and dwForwardOffset.
dwForwardSize
dwForwardOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field that describes the address's forwarding information. This information is an array of dwForwardNumEntries elements, of type LINEFORWARD. The offsets of the addresses in the array are relative to the beginning of the LINEADDRESSSTATUS structure. The offsets dwCallerAddressOffset and dwDestAddressOffset in the variably sized field of type LINEFORWARD pointed to by dwForwardSize and dwForwardOffset are relative to the beginning of the LINEADDRESSSTATUS data structure (the "root" container).
dwTerminalModesSize
dwTerminalModesOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized device field containing an array with DWORD-sized entries, that use one or more of the LINETERMMODE_ constants. This array is indexed by terminal identifiers, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this address.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This data structure is returned by the lineGetAddressStatus function. When items in this data structure change as a consequence of activities on the address, a LINE_ADDRESSSTATE message is sent to the application. A parameter to this message is the address state, one of the LINEADDRESSSTATE_ constants, which indicates that the status item in this record changed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINE_ADDRESSSTATE, LINEFORWARD, lineGetAddressStatus, TSPI_lineGetAddressStatus, lineSetTerminal


LINEAPPINFO

The LINEAPPINFO structure contains information about the application that is currently running. The LINEDEVSTATUS structure can contain an array of LINEAPPINFO structures.

typedef struct lineappinfo_tag {
  DWORD  dwMachineNameSize;
  DWORD  dwMachineNameOffset;
  DWORD  dwUserNameSize;
  DWORD  dwUserNameOffset;
  DWORD  dwModuleFilenameSize;
  DWORD  dwModuleFilenameOffset;
  DWORD  dwFriendlyNameSize;
  DWORD  dwFriendlyNameOffset;
  DWORD  dwMediaModes;
  DWORD  dwAddressID;
} LINEAPPINFO, *LPLINEAPPINFO;

Members

dwMachineNameSize
dwMachineNameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of a string specifying the name of the computer on which the application is executing.
dwUserNameSize
dwUserNameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of a string specifying the user name under whose account the application is running.
dwModuleFilenameSize
dwModuleFilenameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of a string specifying the module filename of the application. This string can be used in a call to lineHandoff to perform a directed handoff to the application.
dwFriendlyNameSize
dwFriendlyNameOffset
Size, in bytes, and offset from the beginning of LINEDEVSTATUS of the string provided by the application to lineInitialize or lineInitializeEx, which should be used in any display of applications to the user.
dwMediaModes
The media types for which the application has requested ownership of new calls; zero if when it opened the line dwPrivileges did not include LINECALLPRIVILEGE_OWNER.
dwAddressID
If the line handle was opened using LINEOPENOPTION_SINGLEADDRESS, contains the address identifier specified; set to 0xFFFFFFFF if the single address option was not used.

An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEDEVSTATUS, lineHandoff, lineInitialize, lineInitializeEx, lineGetLineDevStatus, TSPI_lineGetLineDevStatus


LINECALLHUBTRACKINGINFO

The LINECALLHUBTRACKINGINFO structure contains information that reports the type of tracking available to a call hub. This structure is exposed only to applications that negotiate a TAPI version of 3.0 or higher.

The TSPI_lineSetCallHubTracking function and the TSPI_lineGetCallHubTracking function use the LINECALLHUBTRACKINGINFO structure.

typedef struct linecallhubtrackinginfo_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwAvailableTracking;
  DWORD  dwCurrentTracking;
} LINECALLHUBTRACKINGINFO, FAR *LPLINECALLHUBTRACKINGINFO;

Members

dwTotalSize
Total size, in bytes.
dwNeededSize
Size needed, in bytes.
dwUsedSize
Size used, in bytes.
dwAvailableTracking
Available tracking, as represented by a LINECALLHUBTRACKING.constant.
dwCurrentTracking
Current tracking, as represented by a LINECALLHUBTRACKING constant.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi.h.

See Also

LINECALLHUBTRACKING, TSPI_lineSetCallHubTracking, TSPI_lineGetCallHubTracking


LINECALLINFO

The LINECALLINFO structure contains information about a call. This information remains relatively fixed for the duration of the call. Multiple functions use LINECALLINFO. The structure is returned by the lineGetCallInfo function and the TSPI_lineGetCallInfo function. If a part of the structure does change, then a LINE_CALLINFO message is sent to the application indicating which information item has changed.

Dynamically changing information about a call, such as call progress status, is available in the LINECALLSTATUS structure, returned by a call to the lineGetCallStatus function.

typedef struct linecallinfo_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

 HLINE  hLine;
  DWORD  dwLineDeviceID;
  DWORD  dwAddressID;

  DWORD  dwBearerMode;
  DWORD  dwRate;
   DWORD  dwMediaMode;

  DWORD  dwAppSpecific;
  DWORD  dwCallID;
  DWORD  dwRelatedCallID;
  DWORD  dwCallParamFlags;
  DWORD  dwCallStates;

  DWORD  dwMonitorDigitModes;
  DWORD  dwMonitorMediaModes;
 LINEDIALPARAMS  DialParams;

  DWORD  dwOrigin;
  DWORD  dwReason;
  DWORD  dwCompletionID;

  DWORD  dwNumOwners;
  DWORD  dwNumMonitors;

  DWORD  dwCountryCode;
  DWORD  dwTrunk;

  DWORD  dwCallerIDFlags;
  DWORD  dwCallerIDSize;
  DWORD  dwCallerIDOffset;
  DWORD  dwCallerIDNameSize;
  DWORD  dwCallerIDNameOffset;

  DWORD  dwCalledIDFlags;
  DWORD  dwCalledIDSize;
  DWORD  dwCalledIDOffset;
  DWORD  dwCalledIDNameSize;
  DWORD  dwCalledIDNameOffset;

  DWORD  dwConnectedIDFlags;
  DWORD  dwConnectedIDSize;
  DWORD  dwConnectedIDOffset;
  DWORD  dwConnectedIDNameSize;
  DWORD  dwConnectedIDNameOffset;

  DWORD  dwRedirectionIDFlags;
  DWORD  dwRedirectionIDSize;
  DWORD  dwRedirectionIDOffset;
  DWORD  dwRedirectionIDNameSize;
  DWORD  dwRedirectionIDNameOffset;

  DWORD  dwRedirectingIDFlags;
  DWORD  dwRedirectingIDSize;
  DWORD  dwRedirectingIDOffset;
  DWORD  dwRedirectingIDNameSize;
  DWORD  dwRedirectingIDNameOffset;

  DWORD  dwAppNameSize;
  DWORD  dwAppNameOffset;
  DWORD  dwDisplayableAddressSize;
  DWORD  dwDisplayableAddressOffset;

  DWORD  dwCalledPartySize;
  DWORD  dwCalledPartyOffset;

  DWORD  dwCommentSize;
  DWORD  dwCommentOffset;

  DWORD  dwDisplaySize;
  DWORD  dwDisplayOffset;

  DWORD  dwUserUserInfoSize;
  DWORD  dwUserUserInfoOffset;

  DWORD  dwHighLevelCompSize;
  DWORD  dwHighLevelCompOffset;

  DWORD  dwLowLevelCompSize;
  DWORD  dwLowLevelCompOffset;

  DWORD  dwChargingInfoSize;
  DWORD  dwChargingInfoOffset;

  DWORD  dwTerminalModesSize;
  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;

  DWORD  dwCallTreatment;

  DWORD  dwCallDataSize;
  DWORD  dwCallDataOffset;

  DWORD  dwSendingFlowspecSize;
  DWORD  dwSendingFlowspecOffset;

  DWORD  dwReceivingFlowspecSize;
  DWORD  dwReceivingFlowspecOffset;

  DWORD  dwCallerIDAddressType;      //TAPI Version 3.0
  DWORD  dwCalledIDAddressType;      //TAPI Version 3.0
  DWORD  dwConnectedIDAddressType;   //TAPI Version 3.0
  DWORD  dwRedirectionIDAddressType; //TAPI Version 3.0
  DWORD  dwRedirectingIDAddressType; //TAPI Version 3.0

} LINECALLINFO, FAR *LPLINECALLINFO;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
hLine
The handle for the line device with which this call is associated.
dwLineDeviceID
The device identifier of the line device with which this call is associated.
dwAddressID
The address identifier of the address on the line on which this call exists. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwBearerMode
The current bearer mode of the call. This member uses one of the LINEBEARERMODE_ constants.
dwRate
The rate of the call's data stream in bps (bits per second).
dwMediaMode
Specifies the media type of the information stream currently on the call. This is the media type as determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA message. This member is not directly affected by the LINE_MONITORMEDIA messages. This member uses the LINEMEDIAMODE_ constants.
dwAppSpecific
Not interpreted by the API implementation and service provider. It can be set by any owner application of this call with the lineSetAppSpecific function.
dwCallID
In some telephony environments, the switch or service provider can assign a unique identifier to each call. This allows the call to be tracked across transfers, forwards, or other events. The domain of these call IDs and their scope is service provider-defined. The dwCallID member makes this unique identifier available to the applications.
dwRelatedCallID
Telephony environments that use the call ID often may find it necessary to relate one call to another. The dwRelatedCallID member may be used by the service provider for this purpose.
dwCallParamFlags
A collection of call-related parameters when the call is outgoing. These are the same call parameters specified in lineMakeCall, one or more of the LINECALLPARAMFLAGS_ constants.
dwCallStates
The call states, one or more of the LINECALLSTATE_ constants, for which the application can be notified on this call. The dwCallStates member is constant in LINECALLINFO and does not change depending on the call state.
dwMonitorDigitModes
The various digit modes, one or more of the LINEDIGITMODE_ constants, for which monitoring is currently enabled.
dwMonitorMediaModes
The various media types for which monitoring is currently enabled, one or more of the LINEMEDIAMODE_ constants.
DialParams
The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either lineMakeCall or lineSetCallParams, their values are the same as the defaults used in the LINEDEVCAPS structure.
dwOrigin
Identifies where the call originated, one of the LINECALLORIGIN_ constants.
dwReason
The reason why the call occurred, one of the LINECALLREASON_ constants.
dwCompletionID
The completion identifier for the incoming call if it is the result of a completion request that terminates. This identifier is meaningful only if dwReason is LINECALLREASON_CALLCOMPLETION.
dwNumOwners
The number of application modules with different call handles with owner privilege for the call.
dwNumMonitors
The number of application modules with different call handles with monitor privilege for the call.
dwCountryCode
The country code of the destination party. Zero if unknown.
dwTrunk
The number of the trunk over which the call is routed. This member is used for both incoming and outgoing calls. The dwTrunk member should be set to 0xFFFFFFFF if it is unknown.
dwCallerIDFlags
Determines the validity and content of the caller, or originator, party identifier information. This member uses one of the LINECALLPARTYID_ constants.
dwCallerIDSize
dwCallerIDOffset
The size, in bytes, of the variably sized field containing the caller party ID number information, and the offset, in bytes, from the beginning of this data structure.
dwCallerIDNameSize
dwCallerIDNameOffset
The size, in bytes, of the variably sized field containing the caller party ID name information, and the offset, in bytes, from the beginning of this data structure.
dwCalledIDFlags
Determines the validity and content of the called-party ID information. The called party corresponds to the originally addressed party. This member uses one of the LINECALLPARTYID_ constants.
dwCalledIDSize
dwCalledIDOffset
The size, in bytes, of the variably sized field containing the called-party ID number information, and the offset, in bytes, from the beginning of this data structure.
dwCalledIDNameSize
dwCalledIDNameOffset
The size, in bytes, of the variably sized field containing the called-party ID name information, and the offset, in bytes, from the beginning of this data structure.
dwConnectedIDFlags
Determines the validity and content of the connected party ID information. The connected party is the party that was actually connected to. This may be different from the called-party ID if the call was diverted. This member uses one of the LINECALLPARTYID_ constants.
dwConnectedIDSize
dwConnectedIDOffset
The size, in bytes, of the variably sized field containing the connected party identifier number information, and the offset, in bytes, from the beginning of this data structure.
dwConnectedIDNameSize
dwConnectedIDNameOffset
The size, in bytes, of the variably sized field containing the connected party identifier name information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectionIDFlags
Determines the validity and content of the redirection party identifier information. The redirection party identifies the address to which the session was redirected. This member uses one of the LINECALLPARTYID_ constants.
dwRedirectionIDSize
dwRedirectionIDOffset
The size, in bytes, of the variably sized field containing the redirection party identifier number information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectionIDNameSize
dwRedirectionIDNameOffset
The size, in bytes, of the variably sized field containing the redirection party identifier name information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectingIDFlags
Determines the validity and content of the redirecting party identifier information. The redirecting party identifies the address which redirect the session. This member uses one of the LINECALLPARTYID_ constants.
dwRedirectingIDSize
dwRedirectingIDOffset
The size, in bytes, of the variably sized field containing the redirecting party identifier number information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectingIDNameSize
dwRedirectingIDNameOffset
The size, in bytes, of the variably sized field containing the redirecting party identifier name information, and the offset, in bytes, from the beginning of this data structure.
dwAppNameSize
dwAppNameOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field holding the user-friendly application name of the application that first originated, accepted, or answered the call. This is the name that an application can specify in lineInitializeEx. If the application specifies no such name, then the application's module filename is used instead.
dwDisplayableAddressSize
dwDisplayableAddressOffset
The displayable string is used for logging purposes. The information is obtained from LINECALLPARAMS for functions that initiate calls. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
The size, in bytes, of the variably sized field holding a user-friendly description of the called party, and the offset, in bytes, from the beginning of this data structure. This information can be specified with lineMakeCall and can be optionally specified in the lpCallParams parameter whenever a new call is established. It is useful for call logging purposes.
dwCommentSize
dwCommentOffset
The size, in bytes, of the variably sized field holding a comment about the call provided by the application that originated the call using lineMakeCall, and the offset, in bytes, from the beginning of this data structure. This information can be optionally specified in the lpCallParams parameter whenever a new call is established.
dwDisplaySize
dwDisplayOffset
The size, in bytes, of the variably sized field holding raw display information, and the offset, in bytes, from the beginning of this data structure. Depending on the telephony environment, a service provider may extract functional information from this member pair for formatting and presentation most appropriate for this telephony configuration.
dwUserUserInfoSize
dwUserUserInfoOffset
The size, in bytes, of the variably sized field holding user-user information, and the offset, in bytes, from the beginning of this data structure The protocol discriminator field for the user-user information, if used, appears as the first byte of the data pointed to by dwUserUserInfoOffset, and is accounted for in dwUserUserInfoSize.
dwHighLevelCompSize
dwHighLevelCompOffset
The size, in bytes, of the variably sized field holding high-level compatibility information, and the offset, in bytes, from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).
dwLowLevelCompSize
dwLowLevelCompOffset
The size, in bytes, of the variably sized field holding low-level compatibility information, and the offset, in bytes, from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).
dwChargingInfoSize
dwChargingInfoOffset
The size, in bytes, of the variably sized field holding charging information, and the offset, in bytes, from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).
dwTerminalModesSize
dwTerminalModesOffset
The size, in bytes, of the variably sized device field containing an array with DWORD-sized entries, and the offset, in bytes, from the beginning of this data structure. Array entries are indexed by terminal identifiers, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this call's media stream, as specified by one of the LINETERMMODE_ constants.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably-sized field holding device-specific information, and the offset, in bytes, from the beginning of this data structure.
dwCallTreatment
The call treatment currently being applied on the call or that is applied when the call enters the next applicable state. Can be zero if call treatments are not supported.
dwCallDataSize
dwCallDataOffset
The size, in bytes, and offset from the beginning of LINECALLINFO of the application-settable call data.
dwSendingFlowspecSize
dwSendingFlowspecOffset
The total size, in bytes, and offset from the beginning of LINECALLINFO of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service current in effect in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwReceivingFlowspecSize
dwReceivingFlowspecOffset
The total size, in bytes, and offset from the beginning of LINECALLINFO of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service current in effect in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwCallerIDAddressType
The address type of the caller. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwCalledIDAddressType
The address type of the called party. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwConnectedIDAddressType
The address type of the destination to which the call was actually connected. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwRedirectionIDAddressType
The address type of the new call destination. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwRedirectingIDAddressType
The address type of the location which redirected the call. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The LINECALLINFO data structure contains relatively fixed information about a call. This structure is returned with lineGetCallInfo. When information items in this data structure have changed, a LINE_CALLINFO message is sent to the application. A parameter to this message is the information item or field that changed.

The members dwCallTreatment through dwReceivingFlowspecOffset are available only to applications that open the line device with an API version of 2.0 or later.

Note The preferred format for specification of the contents of the dwCallID field and the other five similar fields (dwCallerIDFlag, dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, and dwCallerIDNameOffset) is the TAPI canonical number format. For example, a ICLID of "4258828080" received from the switch should be converted to "+1 (425) 8828080" before being placed in the LINECALLINFO structure. This standardized format facilitates searching of databases and callback functions implemented in applications.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLINFO, LINE_MONITORMEDIA, LINECALLSTATUS, LINEDEVCAPS, LINEDIALPARAMS, lineGenerateDigits, lineGetCallInfo, TSPI_lineGetCallInfo, lineGetCallStatus, lineInitializeEx, lineMakeCall, lineSecureCall, lineSetAppSpecific, lineSetCallParams, lineSetTerminal, lineTranslateAddress, LINETRANSLATEOUTPUT


LINECALLLIST

The LINECALLLIST structure describes a list of call handles. A structure of this type is returned by the lineGetNewCalls and lineGetConfRelatedCalls functions.

typedef struct linecalllist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwCallsNumEntries;
  DWORD  dwCallsSize;
  DWORD  dwCallsOffset;
} LINECALLLIST, FAR *LPLINECALLLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwCallsNumEntries
The number of handles in the hCalls array.
dwCallsSize
dwCallsOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field (which is an array of HCALL-sized handles).

Remarks

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGetConfRelatedCalls, lineGetNewCalls


LINECALLPARAMS

The LINECALLPARAMS structure describes parameters supplied when making calls using the lineMakeCall and TSPI_lineMakeCall functions. The LINECALLPARAMS structure is also used as a parameter in other operations, such as the lineOpen function.

The comments to the right of the syntax block indicate the default values used when this structure is not provided to lineMakeCall.

typedef struct linecallparams_tag {  // Defaults:
  DWORD  dwTotalSize;          // ---------

  DWORD  dwBearerMode;              // voice
  DWORD  dwMinRate;                 // (3.1kHz)
  DWORD  dwMaxRate;                 // (3.1kHz)
  DWORD  dwMediaMode;               // interactiveVoice

  DWORD  dwCallParamFlags;          // 0
  DWORD  dwAddressMode;             // addressID
  DWORD  dwAddressID;               // (any available)

  LINEDIALPARAMS DialParams;        // (0, 0, 0, 0)

  DWORD  dwOrigAddressSize;         // 0
  DWORD  dwOrigAddressOffset;

  DWORD  dwDisplayableAddressSize;  // 0
  DWORD  dwDisplayableAddressOffset;

  DWORD  dwCalledPartySize;         // 0
  DWORD  dwCalledPartyOffset;

  DWORD  dwCommentSize;             // 0
  DWORD  dwCommentOffset;

  DWORD  dwUserUserInfoSize;        // 0
  DWORD  dwUserUserInfoOffset;

  DWORD  dwHighLevelCompSize;       // 0
  DWORD  dwHighLevelCompOffset;

  DWORD  dwLowLevelCompSize;        // 0
  DWORD  dwLowLevelCompOffset;

  DWORD  dwDevSpecificSize;         // 0
  DWORD  dwDevSpecificOffset;

  DWORD  dwPredictiveAutoTransferStates;//TAPI Version 2.0

  DWORD  dwTargetAddressSize;    //TAPI Version 2.0
  DWORD  dwTargetAddressOffset;  //TAPI Version 2.0

  DWORD  dwSendingFlowspecSize;   //TAPI Version 2.0
  DWORD  dwSendingFlowspecOffset; //TAPI Version 2.0

  DWORD  dwReceivingFlowspecSize;   //TAPI Version 2.0
  DWORD  dwReceivingFlowspecOffset; //TAPI Version 2.0

  DWORD  dwDeviceClassSize;      //TAPI Version 2.0
  DWORD  dwDeviceClassOffset;    //TAPI Version 2.0

  DWORD  dwDeviceConfigSize;     //TAPI Version 2.0
  DWORD  dwDeviceConfigOffset;   //TAPI Version 2.0

  DWORD  dwCallDataSize;         //TAPI Version 2.0
  DWORD  dwCallDataOffset;       //TAPI Version 2.0

  DWORD  dwNoAnswerTimeout;      //TAPI Version 2.0

  DWORD  dwCallingPartyIDSize;   //TAPI Version 2.0
  DWORD  dwCallingPartyIDOffset; //TAPI Version 2.0

  DWORD  dwAddressType;          //TAPI Version 3.0
} LINECALLPARAMS, FAR *LPLINECALLPARAMS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure. This size should be big enough to hold all the fixed and variably sized portions of this data structure.
dwBearerMode
The bearer mode for the call. This member uses one of the LINEBEARERMODE_ constants.

If dwBearerMode is zero, the default value is LINEBEARERMODE_VOICE.

dwMinRate
dwMaxRate
The data rate range requested for the call's data stream in bps (bits per second). When making a call, the service provider attempts to provide the highest available rate in the requested range. If a specific data rate is required, both min and max should be set to that value. If an application works best with one rate but is able to degrade to lower rates, the application should specify these as the maximum and minimum rates, respectively. If dwMaxRate is zero, the default value is as specified by the dwMaxRate member of the LINEDEVCAPS structure. This is the maximum rate supported by the device.
dwMediaMode
The expected media type of the call. This member uses one of the LINEMEDIAMODE_ constants.

If dwMediaMode is zero, the default value is LINEMEDIAMODE_INTERACTIVEVOICE.

dwCallParamFlags
These flags specify a collection of Boolean call-setup parameters. This member uses one or more of the LINECALLPARAMFLAGS_ constants.
dwAddressMode
The mode by which the originating address is specified. The dwAddressMode member cannot be LINEADDRESSMODE_ADDRESSID for the lineOpen function call. This member uses one of the LINEADDRESSMODE_ constants.
dwAddressID
The address identifier of the originating address if dwAddressMode is set to LINEADDRESSMODE_ADDRESSID. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
DialParams
Dial parameters to be used on this call, of type LINEDIALPARAMS. When a value of 0 is specified for this field, the default value for the field is used as indicated in the DefaultDialParams member of the LINEDEVCAPS structure. If a nonzero value is specified for a field that is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.
dwOrigAddressSize
dwOrigAddressOffset
The size, in bytes, of the variably sized field holding the originating address, and the offset, in bytes, from the beginning of this data structure. The format of this address is dependent on the dwAddressMode member.
dwDisplayableAddressSize
dwDisplayableAddressOffset
The displayable string is used for logging purposes. The content of these members is recorded in the dwDisplayableAddressOffset and dwDisplayableAddressSize members of the call's LINECALLINFO message. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
The size, in bytes, of the variably sized field holding called-party information, and the offset, in bytes, from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.
dwCommentSize
dwCommentOffset
The size, in bytes, of the variably sized field holding comments about the call, and the offset, in bytes, from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.
dwUserUserInfoSize
dwUserUserInfoOffset
The size, in bytes, of the variably sized field holding user-user information, and the offset, in bytes, from the beginning of this data structure. The protocol discriminator field for the user-user information, if required, should appear as the first byte of the data pointed to by dwUserUserInfoOffset, and must be accounted for in dwUserUserInfoSize.
dwHighLevelCompSize
dwHighLevelCompOffset
The size, in bytes, of the variably sized field holding high-level compatibility information, and the offset, in bytes, from the beginning of this data structure
dwLowLevelCompSize
dwLowLevelCompOffset
The size, in bytes, of the variably sized field holding low-level compatibility information, and the offset, in bytes, from the beginning of this data structure.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized field holding device-specific information, and the offset, in bytes, from the beginning of this data structure
dwPredictiveAutoTransferStates
The LINECALLSTATE_ constants, entry into which causes the call to be blind-transferred to the specified target address. Set to zero if automatic transfer is not desired.
dwTargetAddressSize
dwTargetAddressOffset
The size, in bytes, and offset from the beginning of LINECALLPARAMS of a string specifying the target dialable address (not dwAddressID); used in the case of certain automatic actions. In the case of predictive dialing, specifies the address to which the call should be automatically transferred. This is essentially the same string that would be passed to lineBlindTransfer if automatic transfer were not being used. Set to zero if automatic transfer is not desired. In the case of a No Hold Conference, specifies the address that should be conferenced to the call. In the case of a One Step Transfer, specifies the address to dial on the consultation call.
dwSendingFlowspecSize
dwSendingFlowspecOffset
The total size, in bytes, and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwReceivingFlowspecSize
dwReceivingFlowspecOffset
The total size, in bytes, and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwDeviceClassSize
dwDeviceClassOffset
The size, in bytes, and offset from the beginning of LINECALLPARAMS of a null-terminated string (the size includes the NULL) that indicates the device class of the device whose configuration is specified in DeviceConfig. Valid device class strings are the same as those specified for the lineGetID function.
dwDeviceConfigSize
dwDeviceConfigOffset
The number of bytes and offset from the beginning of LINECALLPARAMS of the opaque configuration data structure pointed to by dwDevConfigOffset. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig. If the size is zero, the default device configuration is used. This allows the application to set the device configuration before the call is initiated.
dwCallDataSize
dwCallDataOffset
The size, in bytes, and offset from the beginning of LINECALLPARAMS of the application-settable call data to be initially attached to the call.
dwNoAnswerTimeout
The number of seconds, after the completion of dialing, that the call should be allowed to wait in the PROCEEDING or RINGBACK states, before it is automatically abandoned by the service provider with a LINECALLSTATE_DISCONNECTED and LINEDISCONNECTMODE_NOANSWER. A value of 0 indicates that the application does not desire automatic call abandonment.
dwCallingPartyIDSize
dwCallingPartyIDOffset
The size, in bytes, and offset from the beginning of LINECALLPARAMS of a null-terminated string (the size includes the NULL) that specifies the identity of the party placing the call. If the content of the identifier is acceptable and a path is available, the service provider passes the identifier along to the called party to indicate the identity of the calling party.
dwAddressType
The address type used for the call. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This structure is used as a parameter to lineMakeCall when setting up a call. Its fields allow the application to specify the quality of service requested from the network as well as a variety of ISDN call-setup parameters. If no LINECALLPARAMS structure is supplied to lineMakeCall, a default POTS voice-grade call is requested with the default values listed above.

Note The fields DialParams through dwDevSpecificOffset are ignored when an lpCallParams parameter is specified with the lineOpen function.

The members dwPredictiveAutoTransferStates through dwCallingPartyIDOffset are available only to applications that open the line device with an API version of 2.0 or later.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineBlindTransfer, LINEDEVCAPS, LINEDIALPARAMS, lineGetDevConfig, lineGetID, lineMakeCall, TSPI_lineMakeCall, lineOpen, lineTranslateAddress, LINETRANSLATEOUTPUT, VARSTRING


LINECALLSTATUS

The LINECALLSTATUS structure describes the current status of a call. The information in this structure depends on the device capabilities of the address, the ownership of the call by the invoking application, and the current state of the call being queried. The lineGetCallStatus and TSPI_lineGetCallStatus functions return the LINECALLSTATUS structure.

typedef struct linecallstatus_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwCallState;
  DWORD  dwCallStateMode;
  DWORD  dwCallPrivilege;
  DWORD  dwCallFeatures;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;

  DWORD  dwCallFeatures2;
  SYSTEMTIME  tStateEntryTime;
} LINECALLSTATUS, FAR *LPLINECALLSTATUS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwCallState
Specifies the current call state of the call using one of the LINECALLSTATE_ constants.
dwCallStateMode
The interpretation of the dwCallStateMode member is call-state-dependent. In many cases, the value will be zero. The following table shows dwCallStateMode types for a given dwCallState value.
dwCallState | dwCallStateMode
LINECALLSTATE_BUSY | LINEBUSYMODE_ Constants
LINECALLSTATE_CONNECTED | LINECONNECTEDMODE_ Constants
LINECALLSTATE_DIALTONE | LINEDIALTONEMODE_ Constants
LINECALLSTATE_DISCONNECTED | LINEDISCONNECTMODE_ Constants
LINECALLSTATE_OFFERING | LINEOFFERINGMODE_ Constants
LINECALLSTATE_SPECIALINFO | LINESPECIALINFO_ Constants

dwCallPrivilege
The application's privilege for this call. This member uses one or more of the LINECALLPRIVILEGE_ constants.
dwCallFeatures
These flags indicate the Telephony API functions that can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the call in its current state; a one indicates the feature can be invoked. This member uses LINECALLFEATURE_ Constants.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwCallFeatures2
Indicates additional functions can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. An extension of the dwCallFeatures member. This member uses LINECALLFEATURE2_ Constants.
tStateEntryTime
The Coordinated Universal Time at which the current call state was entered.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The application is sent a LINE_CALLSTATE message whenever the call state of a call changes. This message only provides the new call state of the call. Additional status about a call is available with lineGetCallStatus.

The members dwCallFeatures2 and tStateEntryTime are available only to applications that open the line device with an API version of 2.0 or later.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLSTATE, LINEDIALPARAMS, lineGetCallStatus, TSPI_lineGetCallStatus


LINECALLTREATMENTENTRY

The LINECALLTREATMENTENTRY structure provides information on the type of call treatment, such as music, recorded announcement, or silence, on the current call. The LINEADDRESSCAPS structure can contain an array of LINECALLTREATMENTENTRY structures.

typedef struct linecalltreatmententry_tag {
  DWORD  dwCallTreatmentID;
  DWORD  dwCallTreatmentNameSize;
  DWORD  dwCallTreatmentNameOffset;
} LINECALLTREATMENTENTRY, FAR *LPLINECALLTREATMENTENTRY;

Members

dwCallTreatmentID
One of the LINECALLTREATMENT_ Constants (if the treatment is of a predefined type) or a service provider-specific value.
dwCallTreatmentNameSize
dwCallTreatmentNameOffset
Size, in bytes, (including the terminating NULL) and offset from the beginning of LINEADDRESSCAPS of a null-terminated string identifying the treatment. This would ordinarily describe the content of the music or recorded announcement. If the treatment is of a predefined type, a meaningful name should still be specified, for example, "Silence\0", "Busy Signal\0", "Ringback\0", or "Music\0".

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEADDRESSCAPS, LINECALLTREATMENT_ Constants, lineSetCallTreatment, lineGetAddressCaps


LINECARDENTRY

The LINECARDENTRY structure describes a calling card. The LINETRANSLATECAPS structure can contain an array of LINECARDENTRY structures.

typedef struct linecardentry_tag {
  DWORD  dwPermanentCardID;
  DWORD  dwCardNameSize;
  DWORD  dwCardNameOffset;
  DWORD  dwCardNumberDigits;
  DWORD  dwSameAreaRuleSize;
  DWORD  dwSameAreaRuleOffset;
  DWORD  dwLongDistanceRuleSize;
  DWORD  dwLongDistanceRuleOffset;
  DWORD  dwInternationalRuleSize;
  DWORD  dwInternationalRuleOffset;
  DWORD  dwOptions;
} LINECARDENTRY, FAR *LPLINECARDENTRY;

Members

dwPermanentCardID
The permanent identifier that identifies the card.
dwCardNameSize
dwCardNameOffset
Contains a null-terminated string (size includes the NULL) that describes the card in a user-friendly manner.
dwCardNumberDigits
The number of digits in the existing card number. The card number itself is not returned for security reasons (it is stored in scrambled form by TAPI). The application can use this to insert filler bytes into a text control in "password" mode to show that a number exists.
dwSameAreaRuleSize
dwSameAreaRuleOffset
The offset, in bytes, from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in the same area code. The rule is a null-terminated string.
dwLongDistanceRuleSize
dwLongDistanceRuleOffset
The offset, in bytes, from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in the other areas in the same country/region. The rule is a null-terminated string.
dwInternationalRuleSize
dwInternationalRuleOffset
The offset, in bytes, from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in other countries/regions. The rule is a null-terminated string.
dwOptions
Indicates other settings associated with this calling card, using the LINECARDOPTION_ Constants.

Remarks

Older applications are compiled without knowledge of these new fields, and using a SIZEOF(LINECARDENTRY) smaller than the new size. Because this is an array in the variable portion of a LINETRANSLATECAPS structure, it is imperative that older applications receive LINECARDENTRY structures in the format they previously expected, or they are not able to index properly through the array. The application passes in a dwAPIVersion parameter with the lineGetTranslateCaps function, which can be used for guidance by TAPI in handling this situation. The lineGetTranslateCaps function should use the LINECARDENTRY fields and size that match the indicated API version, when building the LINETRANSLATECAPS structure to be returned to the application.

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGetTranslateCaps, LINETRANSLATECAPS


LINECOUNTRYENTRY

The LINECOUNTRYENTRY structure provides the information for a single country entry. An array of one or more of these structures is part of the LINECOUNTRYLIST structure that is returned by the lineGetCountry function.

typedef struct linecountryentry_tag {
  DWORD  dwCountryID;
  DWORD  dwCountryCode;
  DWORD  dwNextCountryID;
  DWORD  dwCountryNameSize;
  DWORD  dwCountryNameOffset;
  DWORD  dwSameAreaRuleSize;
  DWORD  dwSameAreaRuleOffset;
  DWORD  dwLongDistanceRuleSize;
  DWORD  dwLongDistanceRuleOffset;
  DWORD  dwInternationalRuleSize;
  DWORD  dwInternationalRuleOffset;
} LINECOUNTRYENTRY, FAR *LPLINECOUNTRYENTRY;

Members

dwCountryID
The country/region identifier of the entry. The country/region identifier is an internal identifier that allows multiple entries to exist in the country/region list with the same country code (for example, all countries in North America and the Caribbean share country code 1, but require separate entries in the list).
dwCountryCode
The actual country code of the country/region represented by the entry (that is, the digits that would be dialed in an international call). Only this value should ever be displayed to users (country identifiers should never be displayed, as they would be confusing).
dwNextCountryID
The country identifier of the next entry in the country/region list. Because country codes and identifiers are not assigned in any regular numeric sequence, the country/region list is a single linked list, with each entry pointing to the next. The last country/region in the list has a dwNextCountryID value of zero. When the LINECOUNTRYLIST structure is used to obtain the entire list, the entries in the list are in sequence as linked by their dwNextCountryID members.
dwCountryNameSize
dwCountryNameOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string giving the name of the country/region.
dwSameAreaRuleSize
dwSameAreaRuleOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string containing the dialing rule for direct-dialed calls to the same area code.
dwLongDistanceRuleSize
dwLongDistanceRuleOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string containing the dialing rule for direct-dialed calls to other areas in the same country/region.
dwInternationalRuleSize
dwInternationalRuleOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINECOUNTRYLIST structure of a null-terminated string containing the dialing rule for direct-dialed calls to other countries/regions.

Remarks

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINECOUNTRYLIST, lineGetCountry


LINECOUNTRYLIST

The LINECOUNTRYLIST structure describes a list of countries/regions. This structure can contain an array of LINECOUNTRYENTRY structures. LINECOUNTRYLIST is returned by the lineGetCountry function.

typedef struct linecountrylist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwNumCountries;
  DWORD  dwCountryListSize;
  DWORD  dwCountryListOffset;
} LINECOUNTRYLIST, FAR *LPLINECOUNTRYLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumCountries
The number of LINECOUNTRYENTRY structures present in the array denominated by dwCountryListSize and dwCountryListOffset.
dwCountryListSize
dwCountryListOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of an array of LINECOUNTRYENTRY elements that provide the information on each country/region.

Remarks

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINECOUNTRYENTRY, lineGetCountry


LINEDEVCAPS

The LINEDEVCAPS structure describes the capabilities of a line device. The lineGetDevCaps function and the TSPI_lineGetDevCaps function return the LINEDEVCAPS structure.

typedef struct linedevcaps_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwProviderInfoSize;
  DWORD  dwProviderInfoOffset;

  DWORD  dwSwitchInfoSize;
  DWORD  dwSwitchInfoOffset;

  DWORD  dwPermanentLineID;
  DWORD  dwLineNameSize;
  DWORD  dwLineNameOffset;
  DWORD  dwStringFormat;
  DWORD  dwAddressModes;
  DWORD  dwNumAddresses;
  DWORD  dwBearerModes;
  DWORD  dwMaxRate;
  DWORD  dwMediaModes;

  DWORD  dwGenerateToneModes;
  DWORD  dwGenerateToneMaxNumFreq;
  DWORD  dwGenerateDigitModes;
  DWORD  dwMonitorToneMaxNumFreq;
  DWORD  dwMonitorToneMaxNumEntries;
  DWORD  dwMonitorDigitModes;
  DWORD  dwGatherDigitsMinTimeout;
  DWORD  dwGatherDigitsMaxTimeout;

  DWORD  dwMedCtlDigitMaxListSize;
  DWORD  dwMedCtlMediaMaxListSize;
  DWORD  dwMedCtlToneMaxListSize;
  DWORD  dwMedCtlCallStateMaxListSize;

  DWORD  dwDevCapFlags;
  DWORD  dwMaxNumActiveCalls;
  DWORD  dwAnswerMode;
  DWORD  dwRingModes;
  DWORD  dwLineStates;

  DWORD  dwUUIAcceptSize;
  DWORD  dwUUIAnswerSize;
  DWORD  dwUUIMakeCallSize;
  DWORD  dwUUIDropSize;
  DWORD  dwUUISendUserUserInfoSize;
  DWORD  dwUUICallInfoSize;

  LINEDIALPARAMS  MinDialParams;
  LINEDIALPARAMS  MaxDialParams;
  LINEDIALPARAMS  DefaultDialParams;

  DWORD  dwNumTerminals;
  DWORD  dwTerminalCapsSize;
  DWORD  dwTerminalCapsOffset;
  DWORD  dwTerminalTextEntrySize;
  DWORD  dwTerminalTextSize;
  DWORD  dwTerminalTextOffset;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;

  DWORD  dwLineFeatures;

  DWORD  dwSettableDevStatus;
  DWORD  dwDeviceClassesSize;
  DWORD  dwDeviceClassesOffset;
  GUID   PermanentLineGuid;      //TAPI Version 2.2
  DWORD  dwAddressTypes;         //TAPI Version 3.0
  GUID   ProtocolGuid;           //TAPI Version 3.0
  DWORD  dwAvailableTracking;    //TAPI Version 3.0
} LINEDEVCAPS, FAR *LPLINEDEVCAPS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwProviderInfoSize
dwProviderInfoOffset
The size, in bytes, of the variably sized field containing service provider information, and the offset, in bytes, from the beginning of this data structure. The dwProviderInfoSize/Offset member is intended to provide information about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This information can be useful when a user needs to call customer service with problems regarding the provider.
dwSwitchInfoSize
dwSwitchInfoOffset
The size, in bytes, of the variably sized device field containing switch information, and the offset, in bytes, from the beginning of this data structure. The dwSwitchInfoSize/Offset member is intended to provide information about the switch to which the line device is connected, such as the switch manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the switch.
dwPermanentLineID
The permanent DWORD identifier by which the line device is known in the system's configuration. It is a permanent name for the line device. This permanent name (as opposed to dwDevice ID) does not change as lines are added or removed from the system, and persists through operating system upgrades. It can therefore be used to link line-specific information in .ini files (or other files) in a way that is not affected by adding or removing other lines or by changing the operating system.
dwLineNameSize
dwLineNameOffset
The size, in bytes, of the variably sized device field containing a user configurable name for this line device, and the offset, in bytes, from the beginning of this data structure. This name can be configured by the user when configuring the line device's service provider, and is provided for the user's convenience.
dwStringFormat
The string format used with this line device. This member uses one of the STRINGFORMAT_ Constants.
dwAddressModes
The mode by which the originating address is specified. This member uses the LINEADDRESSMODE_ Constants.
dwNumAddresses
The number of addresses associated with this line device. Individual addresses are referred to by address identifiers. Address identifiers range from zero to one less than the value indicated by dwNumAddresses.
dwBearerModes
Flag array that indicates the different bearer modes that the address is able to support. This member uses one or more of the LINEBEARERMODE_ Constants.
dwMaxRate
Contains the maximum data rate, in bits per second, for information exchange over the call.
dwMediaModes
Flag array that indicates the different media types the address is able to support. This member uses one or more of the LINEMEDIAMODE_ Constants.
dwGenerateToneModes
The different kinds of tones that can be generated on this line. This member uses one or more of the LINETONEMODE_ Constants.
dwGenerateToneMaxNumFreq
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEGENERATETONE data structure when generating a tone using lineGenerateTone. A value of 0 indicates that tone generation is not available.
dwGenerateDigitModes
Specifies the digit modes than can be generated on this line. This member uses one or more of the LINEDIGITMODE_ Constants.
dwMonitorToneMaxNumFreq
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEMONITORTONE data structure when monitoring a general tone using lineMonitorTones. A value of 0 indicates that tone monitor is not available.
dwMonitorToneMaxNumEntries
Contains the maximum number of entries that can be specified in a tone list to lineMonitorTones.
dwMonitorDigitModes
Specifies the digit modes than can be detected on this line. This member uses one or more of the LINEDIGITMODE_ Constants.
dwGatherDigitsMinTimeout
dwGatherDigitsMaxTimeout
These members contain the minimum and maximum values, in milliseconds, that can be specified for both the first digit and inter-digit timeout values used by lineGatherDigits. If both these members are zero, timeouts are not supported.
dwMedCtlDigitMaxListSize
dwMedCtlMediaMaxListSize
dwMedCtlToneMaxListSize
dwMedCtlCallStateMaxListSize
These members contain the maximum number of entries that can be specified in the digit list, the media list, the tone list, and the call state list parameters of lineSetMediaControl respectively.
dwDevCapFlags
Specifies various Boolean device capabilities. This member uses one or more of the LINEDEVCAPFLAGS_ Constants.
dwMaxNumActiveCalls
Provides the maximum number of (minimum bandwidth) calls that can be active (connected) on the line at any one time. The actual number of active calls may be lower if higher bandwidth calls have been established on the line.
dwAnswerMode
Specifies the effect on the active call when answering another offering call on a line device. This member uses one of the LINEANSWERMODE_ Constants.
dwRingModes
Contains the number of different ring modes that can be reported in the LINE_LINEDEVSTATE message with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.
dwLineStates
Specifies the different line status components for which the application may be notified in a LINE_LINEDEVSTATE message on this line. This member uses one or more of the LINEDEVSTATE_ Constants.
dwUUIAcceptSize
Specifies the maximum size of user-user information that can be sent during a call accept.
dwUUIAnswerSize
Specifies the maximum size of user-user information that can be sent during a call answer.
dwUUIMakeCallSize
Specifies the maximum size of user-user information that can be sent during a make call.
dwUUIDropSize
Specifies the maximum size of user-user information that can be sent during a call drop.
dwUUISendUserUserInfoSize
Specifies the maximum size of user-user information that can be sent separately any time during a call with lineSendUserUserInfo.
dwUUICallInfoSize
Specifies the maximum size of user-user information that can be received in the LINECALLINFO structure.
MinDialParams
MaxDialParams
These members contain the minimum and maximum values, in milliseconds, for the dial parameters that can be set for calls on this line. Dialing parameters can be set to values in this range. The granularity of the actual settings is service provider-specific.
DefaultDialParams
Contains the default dial parameters used for calls on this line. These parameter values can be overridden on a per-call basis.
dwNumTerminals
The number of terminals that can be set for this line device, its addresses, or its calls. Individual terminals are referred to by terminal IDs and range from zero to one less than the value indicated by dwNumTerminals.
dwTerminalCapsSize
dwTerminalCapsOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized device field containing an array with entries of type LINETERMCAPS. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the terminal device capabilities of the corresponding terminal.
dwTerminalTextEntrySize
The size, in bytes, of each of the terminal text descriptions pointed at by dwTerminalTextSize/Offset.
dwTerminalTextSize
dwTerminalTextOffset
The size, in bytes, of the variably sized field containing descriptive text about each of the line's available terminals, and the offset, in bytes, from the beginning of this data structure. Each message is dwTerminalTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwLineFeatures
Specifies the features available for this line using the LINEFEATURE_ Constants. Invoking a supported feature requires the line to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This member allows an application to discover which line features can be (and which can never be) supported by the device.
dwSettableDevStatus
The LINEDEVSTATUS values that can be modified using lineSetLineDevStatus.
dwDeviceClassesSize
dwDeviceClassesOffset
Length, in bytes, and offset from the beginning of LINEDEVCAPS of a string consisting of the device class identifiers supported on one or more addresses on this line for use with lineGetID, separated by NULLs; the last identifier in the list is followed by two NULLs.
PermanentLineGuid
The GUID permanently associated with the line device.
dwAddressTypes
The address type used for the call. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
ProtocolGuid
The current TAPI Protocol. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher. The protocols are declared in tapi3.h.
dwAvailableTracking
Available tracking, as represented by a LINECALLHUBTRACKING.constant. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications are compiled without new members in the LINEDEVCAPS structure, and using a SIZEOF LINEDEVCAPS smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetDevCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize member less than the size of the fixed portion of the structure as defined in the specified dwAPIVersion, LINEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetDevCaps, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.

New applications must be cognizant of the API version negotiated, and not examine the contents of members in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

If the LINEBEARERMODE_DATA bit is set in the dwBearerModes member, the dwMaxRate member indicates the maximum rate of digital transmission on the bearer channel. The dwMaxRate member of the LINEDEVCAPS structure can contain valid values even if the dwBearerModes member of the LINEDEVCAPS structure is not set to LINEBEARERMODE_DATA.

If LINEBEARERMODE_DATA is not set in dwBearerModes, but the LINEBEARERMODE_VOICE value is set and the LINEMEDIAMODE_DATAMODEM value is set in the dwMediaModes member, the dwMaxRate member indicates the maximum SYNCHRONOUS (DCE) bit rate on the phone line for the attached modem or functional equivalent. For example, if the modem's fastest modulation speed is V.32bis at 14,400bps, dwMaxRate equals 14400. This is not the fastest DTE port rate (which would most likely be 38400, 57600, or 115200), but the fastest bit rate the modem supports on the phone line.

The application must be careful to check to see that LINEBEARERMODE_DATA is not set, to avoid misinterpreting the dwMaxRate member. It is likely to be 64000 or higher if LINEBEARERMODE_DATA is set.

It should also be noted that if the modem has not been specifically identified (for example, it is a "generic" modem), the figure indicated is a "best guess" based on examination of the modem.

The members dwSettableDevStatus through dwDeviceClassesOffset are available only to applications that open the line device with an API version of 2.0 or later.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINE_LINEDEVSTATE, LINECALLINFO, lineClose, lineDial, lineGatherDigits, LINEGENERATETONE, lineGenerateTone, lineGetDevCaps, TSPI_lineGetDevCaps, lineGetID, lineGetTranslateCaps, lineSendUserUserInfo, lineMakeCall, LINEMONITORTONE, lineMonitorTones, lineSetMediaControl, LINETERMCAPS, lineTranslateAddress, LINETRANSLATECAPS, lineUncompleteCall


LINEDEVSTATUS

The LINEDEVSTATUS structure describes the current status of a line device. The lineGetLineDevStatus function and the TSPI_lineGetLineDevStatus function return the LINEDEVSTATUS structure.

typedef struct linedevstatus_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwNumOpens;
  DWORD  dwOpenMediaModes;
  DWORD  dwNumActiveCalls;
  DWORD  dwNumOnHoldCalls;
  DWORD  dwNumOnHoldPendCalls;
  DWORD  dwLineFeatures;
  DWORD  dwNumCallCompletions;
  DWORD  dwRingMode;
  DWORD  dwSignalLevel;
  DWORD  dwBatteryLevel;
  DWORD  dwRoamMode;

  DWORD  dwDevStatusFlags;

  DWORD  dwTerminalModesSize;
  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;

  DWORD dwAvailableMediaModes;
  DWORD dwAppInfoSize;
  DWORD dwAppInfoOffset;
} LINEDEVSTATUS, FAR *LPLINEDEVSTATUS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumOpens
The number of active opens on the line device.
dwOpenMediaModes
Bit array that indicates for which media types the line device is currently open.
dwNumActiveCalls
The number of calls on the line in call states other than idle, onhold, onholdpendingtransfer, and onholdpendingconference.
dwNumOnHoldCalls
The number of calls on the line in the onhold state.
dwNumOnHoldPendCalls
The number of calls on the line in the onholdpendingtransfer or onholdpendingconference state.
dwLineFeatures
Specifies the line-related API functions that are currently available on this line. This member uses one or more of the LINEFEATURE_ Constants.
dwNumCallCompletions
The number of outstanding call completion requests on the line.
dwRingMode
The current ring mode on the line device.
dwSignalLevel
The current signal level of the connection on the line. This is a value in the range 0x00000000 (weakest signal) to 0x0000FFFF (strongest signal).
dwBatteryLevel
The current battery level of the line device hardware. This is a value in the range 0x00000000 (battery empty) to 0x0000FFFF (battery full).
dwRoamMode
The current roam mode of the line device. This member uses one of the LINEROAMMODE_ Constants.
dwDevStatusFlags
The status flags indicate information such as whether the device is locked. It consists of one or more members of LINEDEVSTATUSFLAGS_ Constants.
dwTerminalModesSize
dwTerminalModesOffset
The size, in bytes, of the variably sized device field containing an array with DWORD-sized entries, and the offset, in bytes, from the beginning of this data structure. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set using the lineSetTerminal function for this line. Each entry uses one or more of the LINETERMMODE_ Constants.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwAvailableMediaModes
Indicates the media types that can be invoked on new calls created on this line device, when the dwLineFeatures member indicates that new calls are possible. If this member is zero, it indicates that the service provider either does not know or cannot indicate which media types are available, in which case any or all of the media types indicated in the dwMediaModes member in LINEDEVCAPS may be available.
dwAppInfoSize
dwAppInfoOffset
Length, in bytes, and offset from the beginning of LINEDEVSTATUS of an array of LINEAPPINFO structures. The dwNumOpens member indicates the number of elements in the array. Each element in the array identifies an application that has the line open.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The members dwAvailableMediaModes through dwAppInfoOffset are available only to applications that open the line device with an API version of 2.0 or later.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGetLineDevStatus, TSPI_lineGetLineDevStatus, LINEAPPINFO, LINEDEVCAPS, lineSetTerminal


LINEDIALPARAMS

The LINEDIALPARAMS structure specifies a collection of dialing-related fields. Call the lineSetCallParams function or the TSPI_lineSetCallParams function to set parameters for a call using the LINEDIALPARAMS structure.

typedef struct linedialparams_tag {
  DWORD  dwDialPause;
  DWORD  dwDialSpeed;
  DWORD  dwDigitDuration;
  DWORD  dwWaitForDialtone;
} LINEDIALPARAMS, FAR *LPLINEDIALPARAMS;

Members

dwDialPause
The duration, in milliseconds, of a comma in the dialable address.
dwDialSpeed
The interdigit time period, in milliseconds, between successive digits.
dwDigitDuration
The duration, in milliseconds, of a digit.
dwWaitForDialtone
The maximum amount of time to wait for a dial tone when a 'W' is used in the dialable address.

Remarks

This structure may not be extended.

When a value of 0 is specified for a field, the default value for that field is used. If a nonzero value is specified for a field that is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.

The lineMakeCall function allows an application to adjust the dialing parameters to be used for the call. The lineSetCallParams function can be used to adjust the dialing parameters of an existing call. The LINECALLINFO structure lists the call's current dialing parameters.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINECALLINFO, LINEDEVCAPS, lineMakeCall, lineSetCallParams, TSPI_lineSetCallParams


LINEEXTENSIONID

The LINEEXTENSIONID structure describes an extension identifier. Extension identifiers are used to identify service provider-specific extensions for line devices. Multiple functions use this structure, including the lineNegotiateAPIVersion function and the TSPI_lineGetExtensionID function.

typedef struct lineextensionid_tag {
  DWORD  dwExtensionID0;
  DWORD  dwExtensionID1;
  DWORD  dwExtensionID2;
  DWORD  dwExtensionID3;
} LINEEXTENSIONID, FAR *LPLINEEXTENSIONID;

Members

dwExtensionID0
dwExtensionID1
dwExtensionID2
dwExtensionID3
These four DWORD members together specify a universally unique extension identifier that identifies a line device class extension.

Remarks

This structure may not be extended.

Extension identifiers are generated using an SDK-provided generation utility.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineNegotiateAPIVersion, TSPI_lineGetExtensionID


LINEFORWARD

The LINEFORWARD structure describes an entry of the forwarding instructions. The LINEFORWARDLIST and the LINEADDRESSSTATUS structures can contain an array of LINEFORWARD structures.

typedef struct lineforward_tag {
  DWORD  dwForwardMode;

  DWORD  dwCallerAddressSize;
  DWORD  dwCallerAddressOffset;

  DWORD  dwDestCountryCode;
  DWORD  dwDestAddressSize;
  DWORD  dwDestAddressOffset;

  DWORD  dwCallerAddressType; // TAPI version 3.1
  DWORD  dwDestAddressType;   // TAPI version 3.1
} LINEFORWARD, FAR *LPLINEFORWARD;

Members

dwForwardMode
The types of forwarding. This member uses one of the LINEFORWARDMODE_ Constants.
dwCallerAddressSize
dwCallerAddressOffset
The size, in bytes, of the variably sized address field containing the address of a caller to be forwarded, and the offset, in bytes, from the beginning of the containing data structure. The dwCallerAddressSize/Offset member is set to zero if dwForwardMode is not one of the following: LINEFORWARDMODE_BUSYNASPECIFIC, LINEFORWARDMODE_NOANSWSPECIFIC, LINEFORWARDMODE_UNCONDSPECIFIC, or LINEFORWARDMODE_BUSYSPECIFIC.
dwDestCountryCode
The country code of the destination address to which the call is to be forwarded.
dwDestAddressSize
dwDestAddressOffset
The size, in bytes, of the variably sized address field containing the address of the address where calls are to be forwarded, and the offset, in bytes, from the beginning of the containing data structure.
dwCallerAddressType
Whistler: The address type of the caller. This member of the structure is available only if the negotiated version of TAPI is 3.1 or higher.
dwDestAddressType
Whistler: The address type for the called destination. This member of the structure is available only if the negotiated version of TAPI is 3.1 or higher.

Remarks

This structure may not be extended.

Each entry in the LINEFORWARD structure specifies a forwarding request.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINEFORWARDLIST, LINEADDRESSSTATUS, lineForward, TSPI_lineForward


LINEFORWARDLIST

The LINEFORWARDLIST structure describes a list of forwarding instructions. This structure can contain an array of LINEFORWARD structures. The lineForward and TSPI_lineForward functions use the LINEFORWARDLIST structure.

typedef struct lineforwardlist_tag {
  DWORD  dwTotalSize;

  DWORD  dwNumEntries;
  LINEFORWARD  ForwardList[1];
} LINEFORWARDLIST, FAR *LPLINEFORWARDLIST;

Members

dwTotalSize
The total size, in bytes, of the data structure.
dwNumEntries
Number of entries in the array specified as ForwardList[ ].
ForwardList[ ]
An array of forwarding instruction. The array's entries are of type LINEFORWARD.

Remarks

This structure may not be extended.

The LINEFORWARDLIST structure defines the forwarding parameters requested for forwarding calls on an address or on all addresses on a line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINEFORWARD, lineForward, TSPI_lineForward


LINEGENERATETONE

The LINEGENERATETONE structure contains information about a tone to be generated. This structure is used by the lineGenerateTone and TSPI_lineGenerateTone functions.

typedef struct linegeneratetone_tag {
  DWORD  dwFrequency;
  DWORD  dwCadenceOn;
  DWORD  dwCadenceOff;
  DWORD  dwVolume;
} LINEGENERATETONE, FAR *LPLINEGENERATETONE;

Members

dwFrequency
The frequency, in hertz, of this tone component. A service provider may adjust (round up or down) the frequency specified by the application to fit its resolution.
dwCadenceOn
The "on" duration, in milliseconds, of the cadence of the custom tone to be generated. Zero means no tone is generated.
dwCadenceOff
The "off" duration, in milliseconds, of the cadence of the custom tone to be generated. Zero means no off time, that is, a constant tone.
dwVolume
The volume level at which the tone is to be generated. A value of 0x0000FFFF represents full volume, and a value of 0x00000000 is silence.

Remarks

This structure may not be extended.

This structure is used only for the generation of tones. It is not used for tone monitoring.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGenerateTone, TSPI_lineGenerateTone


LINEINITIALIZEEXPARAMS

The LINEINITIZALIZEEXPARAMS structure describes parameters supplied when making calls using LINEINITIALIZEEX.

typedef struct lineinitializeexparams_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwOptions;

 union
 {
  HANDLE  hEvent;
  HANDLE  hCompletionPort;
 } Handles;

  DWORD  dwCompletionKey;

} LINEINITIALIZEEXPARAMS, FAR *LPLINEINITIALIZEEXPARAMS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwOptions
One of the LINEINITIALIZEEXOPTION_ Constants. Specifies the event notification mechanism the application desires to use.
hEvent
If dwOptions specifies LINEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this field.
hCompletionPort
If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field the handle of an existing completion port opened using CreateIoCompletionPort.
dwCompletionKey
If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that is returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.

Remarks

See lineInitializeEx for further information on these options.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineInitializeEx


LINELOCATIONENTRY

The LINELOCATIONENTRY structure describes a location used to provide an address translation context. The LINETRANSLATECAPS structure can contain an array of LINELOCATIONENTRY structures.

typedef struct linelocationentry_tag {
  DWORD  dwPermanentLocationID;
  DWORD  dwLocationNameSize;
  DWORD  dwLocationNameOffset;
  DWORD  dwCountryCode;
  DWORD  dwCityCodeSize;
  DWORD  dwCityCodeOffset;
  DWORD  dwPreferredCardID;
  DWORD  dwLocalAccessCodeSize;
  DWORD  dwLocalAccessCodeOffset;
  DWORD  dwLongDistanceAccessCodeSize;
  DWORD  dwLongDistanceAccessCodeOffset;
  DWORD  dwTollPrefixListSize;
  DWORD  dwTollPrefixListOffset;
  DWORD  dwCountryID;
  DWORD  dwOptions;
  DWORD  dwCancelCallWaitingSize;
  DWORD  dwCancelCallWaitingOffset;
} LINELOCATIONENTRY, FAR *LPLINELOCATIONENTRY;

Members

dwPermanentLocationID
The permanent identifier that identifies the location.
dwLocationNameSize
dwLocationNameOffset
Contains a null-terminated string (size includes the NULL) that describes the location in a user-friendly manner.
dwCountryCode
The country code of the location.
dwPreferredCardID
The preferred calling card when dialing from this location.
dwCityCodeSize
dwCityCodeOffset
Contains a null-terminated string specifying the city/area code associated with the location (the size includes the NULL). This information, along with the country code, can be used by applications to "default" entry fields for the user when entering phone numbers, to encourage the entry of proper canonical numbers.
dwLocalAccessCodeSize
dwLocalAccessCodeOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string containing the access code to be dialed before calls to addresses in the local calling area.
dwLongDistanceAccessCodeSize
dwLongDistanceAccessCodeOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string containing the access code to be dialed before calls to addresses outside the local calling area.
dwTollPrefixListSize
dwTollPrefixListOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string containing the toll prefix list for the location. The string contains only prefixes consisting of the digits "0" through "9", separated from each other by a single "," (comma) character.
dwCountryID
The country identifier of the country/region selected for the location. This can be used with the lineGetCountry function to obtain additional information about the specific country/region, such as the country/region name (the dwCountryCode member cannot be used for this purpose because country codes are not unique).
dwOptions
Indicates options in effect for this location, with values taken from the LINELOCATIONOPTION_ Constants.
dwCancelCallWaitingSize
dwCancelCallWaitingOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINETRANSLATECAPS structure of a null-terminated string containing the dial digits and modifier characters that should be prefixed to the dialable string (after the pulse/tone character) when an application sets the LINETRANSLATEOPTION_CANCELCALLWAITING bit in the dwTranslateOptions parameter of lineTranslateAddress. If no prefix is defined, this may be indicated by dwCancelCallWaitingSize being set to zero, or by it being set to 1 and dwCancelCallWaitingOffset pointing to an empty string (single NULL byte).

Remarks

This structure may not be extended.

Older applications are compiled without knowledge of these new fields, and using a SIZEOF LINELOCATIONENTRY smaller than the new size. Because this is an array in the variable portion of a LINETRANSLATECAPS structure, it is imperative that older applications receive LINELOCATIONENTRY structures in the format they previously expected, or they are not able to index through the array properly. The application passes in a dwAPIVersion parameter with the lineGetTranslateCaps function, which can be used for guidance by TAPI in handling this situation. The lineGetTranslateCaps function should use the LINELOCATIONENTRY members and size that match the indicated API version, when building the LINETRANSLATECAPS structure to be returned to the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGetCountry, lineGetTranslateCaps, lineTranslateAddress, LINETRANSLATECAPS


LINEMEDIACONTROLCALLSTATE

The LINEMEDIACONTROLCALLSTATE structure describes a media action to be executed when detecting transitions into one or more call states. The lineSetMediaControl and TSPI_lineSetMediaControl functions use this structure.

typedef struct linemediacontrolcallstate_tag {
  DWORD  dwCallStates;
  DWORD  dwMediaControl;
} LINEMEDIACONTROLCALLSTATE, FAR *LPLINEMEDIACONTROLCALLSTATE;

Members

dwCallStates
Specifies one or more call states. This member uses one of the LINECALLSTATE_ Constants.
dwMediaControl
The media control action. This member uses one of the LINEMEDIACONTROL_ Constants.

Remarks

This structure may not be extended.

The LINEMEDIACONTROLCALLSTATE structure defines a triple <call state(s), media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media control actions triggered by the transition to the call state of the given call. When a transition to a listed call state is detected, the corresponding action on the media stream is invoked.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGenerateDigits, lineSetMediaControl, TSPI_lineSetMediaControl


LINEMEDIACONTROLDIGIT

The LINEMEDIACONTROLDIGIT structure describes a media action to be executed when detecting a digit. It is used as an entry in an array. The lineSetMediaControl and TSPI_lineSetMediaControl functions use this structure.

typedef struct linemediacontroldigit_tag {
  DWORD  dwDigit;
  DWORD  dwDigitModes;
  DWORD  dwMediaControl;
} LINEMEDIACONTROLDIGIT, FAR *LPLINEMEDIACONTROLDIGIT;

Members

dwDigit
The low-order byte of this DWORD specifies the digit in whose detection is to trigger a media action. Valid digits depend on the media type.
dwDigitModes
The digit mode(s) to monitor. This member uses one or more of the LINEDIGITMODE_ Constants.
dwMediaControl
The media control action. This member uses one of the LINEMEDIACONTROL_ Constants.

Remarks

This structure may not be extended.

The LINEMEDIACONTROLMEDIA structure defines a triple <digit, digit mode(s), media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media control actions triggered by digits detected on a given call. When a listed digit is detected, then the corresponding action on the media stream is invoked.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINEMEDIACONTROLMEDIA, lineSetMediaControl, TSPI_lineSetMediaControl


LINEMEDIACONTROLMEDIA

The LINEMEDIACONTROLMEDIA structure describes a media action to be executed when detecting a media type change. It is used as an entry in an array. The lineSetMediaControl and TSPI_lineSetMediaControl functions use this structure.

typedef struct linemediacontrolmedia_tag {
  DWORD  dwMediaModes;
  DWORD  dwDuration;
  DWORD  dwMediaControl;
} LINEMEDIACONTROLMEDIA, FAR *LPLINEMEDIACONTROLMEDIA;

Members

dwMediaModes
One or more media types. This member uses one of the LINEMEDIAMODE_ Constants.
dwDuration
The duration, in milliseconds, during which the media type should be present before the application should be notified or media control action should be taken.
dwMediaControl
The media control action. This member uses one of the LINEMEDIACONTROL_ Constants.

Remarks

This structure may not be extended.

The LINEMEDIACONTROLMEDIA structure defines a triple <media type(s), duration, media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media control actions triggered by media type changes for a given call. When a change to a listed media type is detected, then the corresponding action on the media stream is invoked.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineSetMediaControl, TSPI_lineSetMediaControl


LINEMEDIACONTROLTONE

The LINEMEDIACONTROLTONE structure describes a media action to be executed when a tone has been detected. It is used as an entry in an array. The lineSetMediaControl and TSPI_lineSetMediaControl functions use this structure.

typedef struct linemediacontroltone_tag {
  DWORD  dwAppSpecific;
  DWORD  dwDuration;
  DWORD  dwFrequency1;
  DWORD  dwFrequency2;
  DWORD  dwFrequency3;
  DWORD  dwMediaControl;
} LINEMEDIACONTROLTONE, FAR *LPLINEMEDIACONTROLTONE;

Members

dwAppSpecific
Used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific member is passed back to the application.
dwDuration
The duration, in milliseconds, during which the tone should be present before a detection is made.
dwFrequency1
dwFrequency2
dwFrequency3
The frequency, in hertz, of a component of the tone. If fewer than three frequencies are needed in the tone, a value of 0 should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be use for silence detection.
dwMediaControl
The media control action. This member uses one of the LINEMEDIACONTROL_ Constants.

Remarks

This structure may not be extended.

The LINEMEDIACONTROLTONE structure defines a tuple <tone, media-control action>. An array of these tuples is passed to the lineSetMediaControl function to set media control actions triggered by media type changes for a given call. When a change to a listed media type is detected, the corresponding action on the media stream is invoked.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineSetMediaControl, TSPI_lineSetMediaControl


LINEMESSAGE

The LINEMESSAGE structure contains parameter values specifying a change in status of the line the application currently has open. The lineGetMessage function returns the LINEMESSAGE structure.

typedef struct linemessage_tag {
  DWORD  hDevice;
  DWORD  dwMessageID;
  DWORD_PTR  dwCallbackInstance;
  DWORD_PTR  dwParam1;
  DWORD_PTR  dwParam2;
  DWORD_PTR  dwParam3;
} LINEMESSAGE, FAR *LPLINEMESSAGE;

Members

hDevice
A handle to either a line device or a call. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMessageID.
dwMessageID
A line or call device message.
dwCallbackInstance
Instance data passed back to the application, which was specified by the application in the dwCallBackInstance parameter of lineInitializeEx. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For information about parameter values passed in this structure, see Line Device Messages.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineInitializeEx, lineGetMessage


LINEMONITORTONE

The LINEMONITORTONE structure describes a tone to be monitored. This is used as an entry in an array. The lineMonitorTones and TSPI_lineMonitorTones functions use this structure.

typedef struct linemonitortone_tag {
  DWORD  dwAppSpecific;
  DWORD  dwDuration;
  DWORD  dwFrequency1;
  DWORD  dwFrequency2;
  DWORD  dwFrequency3;
} LINEMONITORTONE, FAR *LPLINEMONITORTONE;

Members

dwAppSpecific
Used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific member is passed back to the application.
dwDuration
The duration, in milliseconds, during which the tone should be present before a detection is made.
dwFrequency1
dwFrequency2
dwFrequency3
The frequency, in hertz, of a component of the tone. If fewer than three frequencies are needed in the tone, a value of 0 should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be used for silence detection.

Remarks

This structure may not be extended.

The LINEMONITORTONE structure defines a tone for the purpose of detection. An array of tones is passed to the lineMonitorTones function which monitors these tones and sends a LINE_MONITORTONE message to the application when a detection is made.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINE_MONITORTONE, lineMonitorTones, TSPI_lineMonitorTones


LINEPROVIDERENTRY

The LINEPROVIDERENTRY structure provides the information for a single service provider entry. An array of these structures is returned as part of the LINEPROVIDERLIST structure returned by the function lineGetProviderList.

typedef struct lineproviderentry_tag {
  DWORD  dwPermanentProviderID;
  DWORD  dwProviderFilenameSize;
  DWORD  dwProviderFilenameOffset;
} LINEPROVIDERENTRY, FAR *LPLINEPROVIDERENTRY;

Members

dwPermanentProviderID
The permanent provider identifier of the entry.
dwProviderFilenameSize
dwProviderFilenameOffset
The size, in bytes, and the offset, in bytes, from the beginning of the LINEPROVIDERLIST structure of a null-terminated string containing the filename (path) of the service provider DLL (.TSP) file.

Remarks

Not extensible.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGetProviderList, LINEPROVIDERLIST


LINEPROVIDERLIST

The LINEPROVIDERLIST structure describes a list of service providers. A structure of this type is returned by the lineGetProviderList function. The LINEPROVIDERLIST structure can contain an array of LINEPROVIDERENTRY structures.

typedef struct lineproviderlist_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwNumProviders;
  DWORD  dwProviderListSize;
  DWORD  dwProviderListOffset;
} LINEPROVIDERLIST, FAR *LPLINEPROVIDERLIST;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumProviders
The number of LINEPROVIDERENTRY structures present in the array denominated by dwProviderListSize and dwProviderListOffset.
dwProviderListSize
dwProviderListOffset
The size, in bytes, and the offset, in bytes, from the beginning of this data structure of an array of LINEPROVIDERENTRY elements, which provide the information on each service provider.

Remarks

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINEPROVIDERENTRY, lineGetProviderList


LINEREQMEDIACALL

The LINEREQMEDIACALL structure describes a request initiated by a call to the lineGetRequest function.

typedef struct linereqmediacall_tag{
  HWND        hWnd;
  WPARAM      wRequestID;
  char        szDeviceClass[TAPIMAXDEVICECLASSSIZE];
  unsigned char   ucDeviceID[TAPIMAXDEVICEIDSIZE];
  DWORD       dwSize;
  DWORD       dwSecure;
  char        szDestAddress[TAPIMAXDESTADDRESSSIZE];
  char        szAppName[TAPIMAXAPPNAMESIZE];
  char        szCalledParty[TAPIMAXCALLEDPARTYSIZE];
  char        szComment[TAPIMAXCOMMENTSIZE];
} LINEREQMEDIACALL, FAR *LPLINEREQMEDIACALL;

Members

hWnd
Handle to the window of the application which made the request.
wRequestID
Identifier of the request. Used to match an asynchronous response.
szDeviceClass[TAPIMAXDEVICECLASSSIZE]
The device class required to fill the request.
ucDeviceID[TAPIMAXDEVICEIDSIZE]
The device identifier.
dwSize
Size in bytes of this structure.
dwSecure
TBD
szDestAddress[TAPIMAXDESTADDRESSSIZE]
Destination address.
szAppName[TAPIMAXAPPNAMESIZE]
Name of application which made the request.
szCalledParty[TAPIMAXCALLEDPARTYSIZE]
Called party name.
szComment[TAPIMAXCOMMENTSIZE]
Comment buffer.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineGetRequest


LINEREQMAKECALL

The LINEREQMAKECALL structure describes a request initiated by a call to the lineGetRequest function.

typedef struct linereqmakecall_tag {
  char  szDestAddress[TAPIMAXDESTADDRESSSIZE];
  char  szAppName[TAPIMAXAPPNAMESIZE];
  char  szCalledParty[TAPIMAXCALLEDPARTYSIZE];
  char  szComment[TAPIMAXCOMMENTSIZE];
} LINEREQMAKECALL, FAR *LPLINEREQMAKECALL;

Members

szDestAddress[TAPIMAXADDRESSSIZE]
The null-terminated destination address of the make-call request. The address can use the canonical address format or the dialable address format. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator. Longer strings are truncated.
szAppName[TAPIMAXAPPNAMESIZE]
The null-terminated user-friendly application name or filename of the application that originated the request. The maximum length of the address is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator.
szCalledParty[TAPIMAXCALLEDPARTYSIZE]
The null-terminated user-friendly called-party name. The maximum length of the called-party information is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator.
szComment[TAPIMAXCOMMENTSIZE]
The null-terminated comment about the call request. The maximum length of the comment string is TAPIMAXCOMMENTSIZE characters, which includes the NULL terminator.

Remarks

This structure may not be extended.

The szDestAddress member contains the address of the remote party; the other members are useful for logging purposes. An application must use this structure to interpret the request buffer it received from lineGetRequest with the LINEREQUESTMODE_MAKECALL request mode.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineGetRequest


LINETERMCAPS

The LINETERMCAPS structure describes the capabilities of a line's terminal device. The LINEDEVCAPS structure can contain an array of LINETERMCAPS structures.

typedef struct linetermcaps_tag {
  DWORD  dwTermDev;
  DWORD  dwTermModes;
  DWORD  dwTermSharing;
} LINETERMCAPS, FAR *LPLINETERMCAPS;

Members

dwTermDev
The device type of the terminal. This member uses one of the LINETERMDEV_ Constants.
dwTermModes
The terminal mode(s) the terminal device is able to deal with. This member uses one of the LINETERMMODE_ Constants.
dwTermSharing
Specifies how the terminal device is shared between line devices. This member uses one of the LINETERMSHARING_ Constants.

Remarks

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineSetTerminal, LINEDEVCAPS, lineGetDevCaps, TSPI_lineGetDevCaps


LINETRANSLATECAPS

The LINETRANSLATECAPS structure describes the address translation capabilities. This structure can contain an array of LINELOCATIONENTRY structures and an array of LINECARDENTRY structures. The LINETRANSLATECAPS structure is returned by the lineGetTranslateCaps function.

typedef struct linetranslatecaps_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwNumLocations;
  DWORD  dwLocationListSize;
  DWORD  dwLocationListOffset;

  DWORD  dwCurrentLocationID;
  DWORD  dwNumCards;
  DWORD  dwCardListSize;
  DWORD  dwCardListOffset;

  DWORD  dwCurrentPreferredCardID;
} LINETRANSLATECAPS, FAR *LPLINETRANSLATECAPS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwNumLocations
The number of entries in the LocationList. It includes all locations defined, including zero (default).
dwLocationListSize
dwLocationListOffset
List of locations known to the address translation. The list consists of a sequence of LINELOCATIONENTRY structures. The dwLocationListOffset member points to the first byte of the first LINELOCATIONENTRY structure, and the dwLocationListSize member indicates the total number of bytes in the entire list.
dwCurrentLocationID
The dwPermanentLocationID member from the LINELOCATIONENTRY structure for the CurrentLocation.
dwNumCards
The number of entries in the CardList.
dwCardListSize
dwCardListOffset
List of calling cards known to the address translation. It includes only non-hidden card entries and always includes card 0 (direct dial). The list consists of a sequence of LINECARDENTRY structures. The dwCardListOffset member points to the first byte of the first LINECARDENTRY structure, and the dwCardListSize member indicates the total number of bytes in the entire list.
dwCurrentPreferredCardID
The dwPreferredCardID member from the LINELOCATIONENTRY structure for the CurrentLocation.

Remarks

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

LINECARDENTRY, LINELOCATIONENTRY, lineGetTranslateCaps


LINETRANSLATEOUTPUT

The LINETRANSLATEOUTPUT structure describes the result of an address translation. The lineTranslateAddress function uses this structure.

typedef struct linetranslateoutput_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwDialableStringSize;
  DWORD  dwDialableStringOffset;
  DWORD  dwDisplayableStringSize;
  DWORD  dwDisplayableStringOffset;

  DWORD  dwCurrentCountry;
  DWORD  dwDestCountry;
  DWORD  dwTranslateResults;
} LINETRANSLATEOUTPUT, FAR *LPLINETRANSLATEOUTPUT;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwDialableStringSize
dwDialableStringOffset
Contains the translated output that can be passed to the lineMakeCall, lineDial, or other function requiring a dialable string. The output is always a null-terminated string (NULL is included in the count in dwDialableStringSize). Ancillary fields such as name and subaddress are included in this output string if they were in the input string. This string may contain private information such as calling card numbers. It should not be displayed to the user, to prevent inadvertent visibility to unauthorized persons.
dwDisplayableStringSize
dwDisplayableStringOffset
Contains the translated output that can be displayed to the user for confirmation. It is identical to DialableString, except that calling card digits are replaced with the "friendly name" of the card enclosed within bracket characters (for example, "[AT&T Card]"), and ancillary fields such as name and subaddress are removed. It should normally be safe to display this string in call-status dialog boxes without exposing private information to unauthorized persons. This information is also appropriate to include in call logs.
dwCurrentCountry
Contains the country code configured in CurrentLocation. This value may be used to control the display by the application of certain user interface elements, for local call progress tone detection, and for other purposes.
dwDestCountry
Contains the destination country code of the translated address. This value may be passed to the dwCountryCode parameter of lineMakeCall and other dialing functions (so that the call progress tones of the destination country/region such as a busy signal are properly detected). This field is set to zero if the destination address passed to lineTranslateAddress is not in canonical format.
dwTranslateResults
Indicates the information derived from the translation process, which may assist the application in presenting user-interface elements. This field uses one of the LINETRANSLATERESULT_ Constants.

Remarks

This structure may not be extended.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

lineDial, lineMakeCall, lineTranslateAddress


Phone Device Structures

The following is the reference for phone device structures, which includes:

  • PHONEBUTTONINFO
  • PHONECAPS
  • PHONEEXTENSIONID
  • PHONEINITIALIZEEXPARAMS
  • PHONEMESSAGE
  • PHONESTATUS
  • VARSTRING


PHONEBUTTONINFO

The PHONEBUTTONINFO structure contains information about a button on a phone device. This structure is used by multiple TAPI and TSPI functions.

typedef struct phonebuttoninfo_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwButtonMode;
  DWORD  dwButtonFunction;
  DWORD  dwButtonTextSize;
  DWORD  dwButtonTextOffset;
  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;
  DWORD  dwButtonState;
} PHONEBUTTONINFO, FAR *LPPHONEBUTTONINFO;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwButtonMode
The mode or general usage class of the button. This member uses one of the PHONEBUTTONMODE_ Constants.
dwButtonFunction
The function assigned to the button. This member uses one of the PHONEBUTTONFUNCTION_ Constants.
dwButtonTextSize
dwButtonTextOffset
The size, in bytes, of the variably sized field containing descriptive text for this button, and the offset, in bytes, from the beginning of this data structure. The format of this information is as specified in the dwStringFormat member of the phone's device capabilities.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwButtonState
For the phoneGetButtonInfo function, this field indicates the current state of the button, using the PHONEBUTTONSTATE_ Constants. This field is ignored by the phoneSetButtonInfo function.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications are compiled without this field in the PHONEBUTTONINFO structure, and using a SIZEOF PHONEBUTTONINFO smaller than the new size. The application passes in a dwAPIVersion parameter with the phoneOpen function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize less than the size of the fixed portion of the structure as defined in the specified dwAPIVersion, PHONEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling the TSPI_phoneGetButtonInfo function, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.

New service providers (which support the new API version) must examine the API version passed in. If the API version is less than the highest version supported by the provider, the service provider must not fill in fields not supported in older API versions, as these would fall in the variable portion of the older structure.

New applications must be cognizant of the API version negotiated, and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

phoneGetButtonInfo, phoneSetButtonInfo, TSPI_phoneGetButtonInfo, TSPI_phoneSetButtonInfo, phoneOpen


PHONECAPS

The PHONECAPS structure describes the capabilities of a phone device. The phoneGetDevCaps and TSPI_phoneGetDevCaps functions return this structure.

typedef struct phonecaps_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwProviderInfoSize;
  DWORD  dwProviderInfoOffset;
  DWORD  dwPhoneInfoSize;
  DWORD  dwPhoneInfoOffset;
  DWORD  dwPermanentPhoneID;
  DWORD  dwPhoneNameSize;
  DWORD  dwPhoneNameOffset;
  DWORD  dwStringFormat;
  DWORD  dwPhoneStates;
  DWORD  dwHookSwitchDevs;
  DWORD  dwHandsetHookSwitchModes;
  DWORD  dwSpeakerHookSwitchModes;
  DWORD  dwHeadsetHookSwitchModes;
  DWORD  dwVolumeFlags;
  DWORD  dwGainFlags;
  DWORD  dwDisplayNumRows;
  DWORD  dwDisplayNumColumns;
  DWORD  dwNumRingModes;
  DWORD  dwNumButtonLamps;
  DWORD  dwButtonModesSize;
  DWORD  dwButtonModesOffset;
  DWORD  dwButtonFunctionsSize;
  DWORD  dwButtonFunctionsOffset;
  DWORD  dwLampModesSize;
  DWORD  dwLampModesOffset;
  DWORD  dwNumSetData;
  DWORD  dwSetDataSize;
  DWORD  dwSetDataOffset;
  DWORD  dwNumGetData;
  DWORD  dwGetDataSize;
  DWORD  dwGetDataOffset;
  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;
  DWORD dwDeviceClassesSize;               //TAPI 2.0
  DWORD dwDeviceClassesOffset;             //TAPI 2.0
  DWORD dwPhoneFeatures;                   //TAPI 2.0
  DWORD dwSettableHandsetHookSwitchModes;  //TAPI 2.0
  DWORD dwSettableSpeakerHookSwitchModes;  //TAPI 2.0
  DWORD dwSettableHeadsetHookSwitchModes;  //TAPI 2.0
  DWORD dwMonitoredHandsetHookSwitchModes; //TAPI 2.0
  DWORD dwMonitoredSpeakerHookSwitchModes; //TAPI 2.0
  DWORD dwMonitoredHeadsetHookSwitchModes; //TAPI 2.0
  GUID PermanentPhoneGuid;                 //TAPI 2.2
} PHONECAPS, FAR *LPPHONECAPS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwProviderInfoSize
dwProviderInfoOffset
The size, in bytes, of the variably sized field containing service provider-specific information, and the offset, in bytes, from the beginning of this data structure.

The dwProviderInfoSize/Offset member provides information about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This information can be useful when a user needs to call customer service with problems regarding the provider.

dwPhoneInfoSize
dwPhoneInfoOffset
The size, in bytes, of the variably sized device field containing phone-specific information, and the offset, in bytes, from the beginning of this data structure.

The dwPhoneInfoSize/Offset member provides information about the attached phone device, such as the phone device manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the phone.

dwPermanentPhoneID
The permanent DWORD identifier by which the phone device is known in the system's configuration.
dwPhoneNameSize
dwPhoneNameOffset
The size, in bytes, of the variably sized device field containing a user configurable name for this phone device, and the offset, in bytes, from the beginning of this data structure This name can be configured by the user when configuring the phone device's service provider and is provided for the user's convenience.
dwStringFormat
The string format to be used with this phone device. This member uses one of the STRINGFORMAT_ Constants.
dwPhoneStates
The state changes for this phone device for which the application can be notified in a PHONE_STATE message. This member one or more of the PHONESTATE_ Constants.
dwHookSwitchDevs
Specifies the phone's hookswitch devices. This member uses one of the PHONEHOOKSWITCHDEV_ Constants.
dwHandsetHookSwitchModes
dwSpeakerHookSwitchModes
dwHeadsetHookSwitchModes
Specifies the phone's hookswitch mode capabilities of the handset, speaker, or headset, respectively. The member is only meaningful if the hookswitch device is listed in dwHookSwitchDevs. This member uses one of the PHONEHOOKSWITCHMODE_ Constants.
dwVolumeFlags
Specifies the volume-setting capabilities of the phone device's speaker components. If the bit in position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's speaker component can be adjusted with phoneSetVolume; otherwise, FALSE.
dwGainFlags
Specifies the gain-setting capabilities of the phone device's microphone components. If the bit position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's microphone component can be adjusted with phoneSetGain; otherwise, FALSE.
dwDisplayNumRows
Specifies the display capabilities of the phone device by describing the number of rows in the phone display. The dwDisplayNumRows and dwDisplayNumColumns members are both zero for a phone device without a display.
dwDisplayNumColumns
Specifies the display capabilities of the phone device by describing the number of columns in the phone display. The dwDisplayNumRows and dwDisplayNumColumns members are both zero for a phone device without a display.
dwNumRingModes
The ring capabilities of the phone device. The phone is able to ring with dwNumRingModes different ring patterns, identified as 1, 2, through dwNumRingModes minus one. If the value of this member is 0, applications have no control over the ring mode of the phone. If the value of this member is greater than 0, it indicates the number of ring modes in addition to silence that are supported by the service provider. A value of 0 in the lpdwRingMode parameter of phoneGetRing or the dwRingMode parameter of phoneSetRing indicates silence (the phone is not ringing or should not be rung), and dwRingMode values of 1 to dwNumRingModes are valid ring modes for the phone device.
dwNumButtonLamps
Specifies the number of button/lamps on the phone device that are detectable in TAPI. Button/lamps are identified by their identifier. Valid button/lamp identifiers range from zero to dwNumButtonLamps minus one. The keypad buttons '0', through '9', '*', and '#' are assigned the identifiers 0 through 12.
dwButtonModesSize
dwButtonModesOffset
The size, in bytes, and the offset from the beginning of this data structure in bytes of the variably sized field containing the button modes of the phone's buttons. The array is indexed by button/lamp identifier. This member uses one of the PHONEBUTTONMODE_ Constants.
dwButtonFunctionsSize
dwButtonFunctionsOffset
The size, in bytes, of the variably sized field containing the button modes of the phone's buttons, and the offset, in bytes, from the beginning of this data structure. This member uses one of the PHONEBUTTONFUNCTION_ Constants. The array is indexed by button/lamp identifier.
dwLampModesSize
dwLampModesOffset
The size, in bytes, of the variably sized field containing the lamp modes of the phone's lamps, and the offset, in bytes, from the beginning of this data structure. The array is indexed by button/lamp identifier. This member uses one of the PHONELAMPMODE_ Constants.
dwNumSetData
The number of different download areas in the phone device. The different areas are referred to using the data IDs 0, 1, , dwNumSetData minus one. If this member is zero, the phone does not support the download capability.
dwSetDataSize
dwSetDataOffset
The size, in bytes, of the variably sized field containing the sizes (in bytes) of the phone's download data areas, and the offset, in bytes, from the beginning of this data structure. This is an array with DWORD-sized elements indexed by data identifier.
dwNumGetData
The number of different upload areas in the phone device. The different areas are referred to using the data IDs 0, 1, , dwNumGetData minus one. If this field is zero, the phone does not support the upload capability.
dwGetDataSize
dwGetDataOffset
The size, in bytes, of the variably sized field containing the sizes (in bytes) of the phone's upload data areas, and the offset, in bytes, from the beginning of this data structure. This is an array with DWORD-sized elements indexed by data identifier.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwDeviceClassesSize
dwDeviceClassesOffset
Length, in bytes, and offset from the beginning of PHONECAPS of a string consisting of the device class identifiers supported on this device for use with phoneGetID, separated by NULLs; the last identifier in the list is followed by two NULLs.
dwPhoneFeatures
These flags indicate which Telephony API functions can be invoked on the phone. A zero indicates the corresponding feature is not implemented and can never be invoked by the application on the phone; a one indicates the feature may be invoked depending on the device state and other factors. This member uses PHONEFEATURE_ Constants.
dwSettableHandsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be set on the handset using phoneSetHookSwitch.
dwSettableSpeakerHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be set on the speakerphone using phoneSetHookSwitch.
dwSettableHeadsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be set on the headset using phoneSetHookSwitch.
dwMonitoredHandsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the handset in a PHONE_STATE message and by phoneGetHookSwitch.
dwMonitoredSpeakerHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the speakerphone in a PHONE_STATE message and by phoneGetHookSwitch.
dwMonitoredHeadsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the headset in a PHONE_STATE message and by phoneGetHookSwitch.
PermanentPhoneGuid
The GUID permanently associated with this phone.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The members dwDeviceClassesSize through dwMonitoredHeadsetHookSwitchModes are available only to applications that open the phone device with an API version of 2.0 or later.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

PHONE_BUTTON, PHONE_CLOSE, PHONE_STATE, phoneGetDevCaps, TSPI_phoneGetDevCaps, phoneGetHookSwitch, phoneGetRing, phoneSetGain, phoneSetHookSwitch, phoneSetRing, phoneSetVolume


PHONEEXTENSIONID

The PHONEEXTENSIONID structure describes an extension identifier. Extension identifiers are used to identify service provider-specific extensions for phone device classes. The phoneNegotiateAPIVersion and TSPI_phoneGetExtensionID functions return this structure.

typedef struct phoneextensionid_tag {
  DWORD  dwExtensionID0;
  DWORD  dwExtensionID1;
  DWORD  dwExtensionID2;
  DWORD  dwExtensionID3;
} PHONEEXTENSIONID, FAR *LPPHONEEXTENSIONID;

Members

dwExtensionID0
dwExtensionID1
dwExtensionID2
dwExtensionID3
These four DWORD members together specify a universally unique extension identifier that identifies a phone device class extension.

Remarks

This structure may not be extended.

Extension identifiers are generated using an SDK-provided generation utility.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

phoneNegotiateAPIVersion, TSPI_phoneGetExtensionID


PHONEINITIALIZEEXPARAMS

The PHONEINITIALIZEEXPARAMS structure contains parameters used to establish the association between an application and TAPI; for example, the application's selected event notification mechanism. The phoneInitializeEx function uses this structure.

typedef struct phoneinitializeexparams_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwOptions;
  union
  {
    HANDLE hEvent;
    HANDLE hCompletionPort;
  } Handles;
  DWORD dwCompletionKey;
} PHONEINITIALIZEEXPARAMS, FAR *LPPHONEINITIALIZEEXPARAMS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwOptions
One of the PHONEINITIALIZEEXOPTION_ Constants. Specifies the event notification mechanism the application desires to use.
hEvent
If dwOptions specifies PHONEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this member.
hCompletionPort
If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this member the handle of an existing completion port opened using CreateIoCompletionPort.
dwCompletionKey
If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that is returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.

Remarks

See phoneInitializeEx for further information on these options.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

phoneInitializeEx


PHONEMESSAGE

The PHONEMESSAGE structure contains the next message queued for delivery to the application. The phoneGetMessage function returns this structure.

typedef struct phonemessage_tag {
  DWORD  hDevice;
  DWORD  dwMessageID;
  DWORD_PTR  dwCallbackInstance;
  DWORD_PTR  dwParam1;
  DWORD_PTR  dwParam2;
  DWORD_PTR  dwParam3;
} PHONEMESSAGE, FAR *LPPHONEMESSAGE;

Members

hDevice
A handle to a phone device.
dwMessageID
A phone message.
dwCallbackInstance
Instance data passed back to the application, which was specified by the application in phoneInitializeEx. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For information about parameter values passed in this structure, see Phone Device Messages.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

phoneInitializeEx, phoneGetMessage


PHONESTATUS

The PHONESTATUS structure describes the current status of a phone device. The phoneGetStatus and TSPI_phoneGetStatus functions return this structure.

typedef struct phonestatus_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwStatusFlags;
  DWORD  dwNumOwners;
  DWORD  dwNumMonitors;
  DWORD  dwRingMode;
  DWORD  dwRingVolume;
  DWORD  dwHandsetHookSwitchMode;
  DWORD  dwHandsetVolume;
  DWORD  dwHandsetGain;
  DWORD  dwSpeakerHookSwitchMode;
  DWORD  dwSpeakerVolume;
  DWORD  dwSpeakerGain;
  DWORD  dwHeadsetHookSwitchMode;
  DWORD  dwHeadsetVolume;
  DWORD  dwHeadsetGain;
  DWORD  dwDisplaySize;
  DWORD  dwDisplayOffset;
  DWORD  dwLampModesSize;
  DWORD  dwLampModesOffset;
  DWORD  dwOwnerNameSize;
  DWORD  dwOwnerNameOffset;
  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;

  DWORD  dwPhoneFeatures;
} PHONESTATUS, FAR *LPPHONESTATUS;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwStatusFlags
Provides a set of status flags for this phone device. This member uses one of the PHONESTATUSFLAGS_ Constants.
dwNumOwners
The number of application modules with owner privilege for the phone.
dwNumMonitors
The number of application modules with monitor privilege for the phone.
dwRingMode
The current ring mode of a phone device.
dwRingVolume
The current ring volume of a phone device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHandsetHookSwitchMode
The current hookswitch mode of the phone's handset. This member uses one of the PHONEHOOKSWITCHMODE_ Constants.
dwHandsetVolume
The current speaker volume of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHandsetGain
The current microphone gain of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwSpeakerHookSwitchMode
The current hookswitch mode of the phone's speakerphone. This member uses one of the PHONEHOOKSWITCHMODE_ Constants.
dwSpeakerVolume
The current speaker volume of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwSpeakerGain
The current microphone gain of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwHeadsetHookSwitchMode
The current hookswitch mode of the phone's headset. This member uses one of the PHONEHOOKSWITCHMODE_ Constants.
dwHeadsetVolume
The current speaker volume of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHeadsetGain
The current microphone gain of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwDisplaySize
dwDisplayOffset
The size, in bytes, of the variably sized field containing the phone's current display information, and the offset, in bytes, from the beginning of this data structure.
dwLampModesSize
dwLampModesOffset
The size, in bytes, of the variably sized field containing the phone's current lamp modes, and the offset, in bytes, from the beginning of this data structure.
dwOwnerNameSize
dwOwnerNameOffset
The size, in bytes, of the variably sized field containing the name of the application that is the current owner of the phone device, and the offset, in bytes, from the beginning of this data structure. The name is the application name provided by the application when it invoked with phoneInitialize or phoneInitializeEx. If no application name was supplied, the application's filename is used instead. If the phone currently has no owner, dwOwnerNameSize is zero.
dwDevSpecificSize
dwDevSpecificOffset
The size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwPhoneFeatures
These flags indicate which Telephony API functions can be invoked on the phone, considering the availability of the feature in the device capabilities, the current device state, and device ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the phone in its current state; a one indicates the feature can be invoked. This member uses one or more of the PHONEFEATURE_ Constants.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The dwPhoneFeatures member is available only to applications that open the phone device with an API version of 2.0 or later.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.

See Also

phoneInitialize, phoneInitializeEx, phoneGetStatus, TSPI_phoneGetStatus


VARSTRING

The VARSTRING structure is used for returning variably sized strings. It is used both by the line device class and the phone device class.

typedef struct varstring_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;
  DWORD  dwStringFormat;
  DWORD  dwStringSize;
  DWORD  dwStringOffset;
} VARSTRING, FAR *LPVARSTRING;

Members

dwTotalSize
The total size, in bytes, allocated to this data structure.
dwNeededSize
The size, in bytes, for this data structure that is needed to hold all the returned information.
dwUsedSize
The size, in bytes, of the portion of this data structure that contains useful information.
dwStringFormat
The format of the string. This member uses one of the STRINGFORMAT_ Constants.
dwStringSize
dwStringOffset
The size, in bytes, of the variably sized device field containing the string information, and the offset, in bytes, from the beginning of this data structure.

Remarks

No extensibility.

If a string cannot be returned in a variable structure, the dwStringSize and dwStringOffset members are set in one of the following ways:

  • dwStringSize and dwStringOffset members are both set to zero.
  • dwStringOffset is nonzero and dwStringSize is zero.
  • dwStringOffset is nonzero, dwStringSize is 1, and the byte at the given offset is zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tapi.h.


TAPI Messages

Messages are used to notify the application of asynchronous events. All of these messages are sent to the application through the message notification mechanism that the application specified in lineInitializeEx.

The message always contains a handle to the relevant object (phone, line, or call), which the application can determine the type of from the message type.

Certain messages are used to notify the application about a change in an object's status. These messages provide the object handle and give an indication of which status item has changed. The application can call the appropriate "get status" function of the object to obtain the object's full status.

When an event occurs, messages can be sent to zero, one, or more applications. The target applications for a message are determined by a number of different factors including the meaning of the message, the application's privilege to the object, whether or not the application initiated the request for which the message is a direct result, and the message masking that has been set by the application. Note the following points about messages:

  • Asynchronous reply messages are only sent to the application that originated the request and cannot be masked.
  • Messages that signal the completion of digit or tone generation or the gathering of digits are only sent to the application that requested the digit or tone generation.
  • Messages that indicate line or address state changes are sent to all applications that have opened the line, so long as the message has been enabled through lineSetStatusMessages.
  • Messages that indicate call state and call information changes are sent to all applications that have a handle to the call.
  • Messages that signal a digit detection, tone detection, or media type detection are sent to the applications that requested monitoring of that event.

This section contains the reference information for the following TAPI messages:

Assisted Telephony Messages

Call Center Messages

Formatted Error Messages

Line Device Messages

Phone Device Messages


Assisted Telephony Messages

The following message is associated with Assisted Telephony.

TAPI_REPLY


TAPI_REPLY

The TAPI_REPLY message is nonfunctional in Win32-based applications and obsolete for all classes of Windows-based applications. It should not be used.


Call Center Messages

Messages are used to notify the application of asynchronous events. This section contains the reference for the following TAPI call center messages:

LINE_AGENTSESSIONSTATUS

LINE_AGENTSPECIFIC

LINE_AGENTSTATUS

LINE_AGENTSTATUSEX

LINE_GROUPSTATUS

LINE_PROXYREQUEST

LINE_PROXYSTATUS

LINE_QUEUESTATUS


LINE_AGENTSESSIONSTATUS

The LINE_AGENTSESSIONSTATUS message is sent when the status of an ACD agent session changes on an agent handler for which the application currently has an open line. This message is generated using the lineProxyMessage function.

LINE_AGENTSESSIONSTATUS
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) hAgentSession;
dwParam2 = (DWORD) AgentSessionStatus;
dwParam3 = (DWORD) AgentSessionStatusDetail;

Parameters

dwDevice
The application's handle to the line device on which the agent session status has changed.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
A handle of the agent session whose status has changed.
dwParam2
Specifies the agent session status that has changed. Can be one or more of the LINE_AGENTSESSIONSTATUS.
dwParam3
If dwParam2 includes the LINEAGENTSTATUSEX_STATE bit, dwParam3 indicates the new value of the agent state, which is one of the LINEAGENTSTATEEX_ constants.

Otherwise, dwParam3 is set to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineGetAgentSessionInfo , lineProxyMessage


LINE_AGENTSPECIFIC

The TAPI LINE_AGENTSPECIFIC message is sent when the status of an ACD agent changes on a line the application currently has open. The application can invoke lineGetAgentStatus to determine the current status of the agent.

LINE_AGENTSPECIFIC
hDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) dwAgentExtensionIDIndex;
dwParam2 = (DWORD) dwHandlerSpecific1;
dwParam3 = (DWORD) dwHandlerSpecific2;

Parameters

hDevice
The application's handle to the line device.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The index into the array of handler extension identifiers in the LINEAGENTCAPS structure of the handler extension with which the message is associated.
dwParam2
Specific to the handler extension. Generally, this value is used to cause the application to invoke a lineAgentSpecific function to fetch further details about the message.
dwParam3
Specific to the handler extension.

Return Values

No return value.

Remarks

The LINE_AGENTSPECIFIC message is not sent to applications that support older versions of TAPI.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEAGENTCAPS, lineAgentSpecific, lineGetAgentStatus


LINE_AGENTSTATUS

The TAPI LINE_AGENTSTATUS message is sent when the status of an ACD agent changes on a line the application currently has open. The application can invoke lineGetAgentStatus to determine the current status of the agent.

LINE_AGENTSTATUS
hDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) dwAddressID;
dwParam2 = (DWORD) AgentStatus;
dwParam3 = (DWORD) AgentStatusDetail;

Parameters

hDevice
The application's handle to the line device on which the agent status has changed.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
Identifier of the address on the line on which the agent status changed. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwParam2
Specifies the agent status that has changed; can be a combination of LINEAGENTSTATUS_ constants.
dwParam3
If dwParam2 includes the LINEAGENTSTATUS_STATE bit, then dwParam3 indicates the new value of the dwState member in LINEAGENTSTATUS. Otherwise, this parameter is set to zero.

Return Values

No return value.

Remarks

The LINE_AGENTSTATUS message is not sent to applications that support older versions of TAPI.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEAGENTSTATUS, lineGetAgentStatus


LINE_AGENTSTATUSEX

The LINE_AGENTSTATUSEX message is sent when the status of an ACD agent changes on an agent handler for which the application currently has an open line. This message is generated using lineProxyMessage function.

LINE_AGENTSTATUSEX
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) hAgent;
dwParam2 = (DWORD) AgentStatus;
dwParam3 = (DWORD) AgentStatusDetail;

Parameters

dwDevice
The application's handle to the line device. This relates to the agent handler.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The handle of the agent whose status has changed.
dwParam2
Specifies the queue status that has changed. Can be one or more of the LINEQUEUESTATUS_ constants.
dwParam3
If dwParam2 includes the LINEAGENTSTATUSEX _STATE bit, dwParam3 indicates the new value of the agent state, which is one of the LINEAGENTSTATEEX_ constants.

Otherwise, dwParam3 is set to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineGetAgentInfo, lineProxyMessage


LINE_GROUPSTATUS

The LINE_GROUPSTATUS message is sent when the status of an ACD group changes on an agent handler for which the application currently has an open line. This message is generated using the lineProxyMessage function.

LINE_GROUPSTATUS
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) GroupStatus;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
The application's handle to the line device. This relates to the agent handler.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Reserved. Set to zero.
dwParam2
Specifies the group status that has changed. The application can invoke lineGetGroupList to determine the changes in available groups. The dwParam2 parameter is one or more of the LINEGROUPSTATUS_ constants.
dwParam3
Reserved. Set to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineGetGroupList


LINE_PROXYREQUEST

The TAPI LINE_PROXYREQUEST message delivers a request to a registered proxy function handler.

LINE_PROXYREQUEST
hDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) lpProxyRequest;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
The application's handle to the line device on which the agent status has changed.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
Pointer to a LINEPROXYREQUEST structure containing the request to be processed by the proxy handler application.
dwParam2
Reserved.
dwParam3
Reserved.

Return Values

No return value.

Remarks

The LINE_PROXYREQUEST message is sent only to the first application that registered to handle proxy requests of the type being delivered.

The application should process the request contained in the proxy buffer and call lineProxyResponse to return data or deliver results. Processing of the request should be done within the context of the application's TAPI callback function only if it can be performed immediately, without waiting for response from any other entity. If the application needs to communicate with other entities (for example, a service provider to handle PBX-based ACD, or any other system service which might result in blocking), then the request should be queued within the application and the callback function exited to avoid delaying the receipt of further TAPI messages by the application.

At the time the LINE_PROXYREQUEST is delivered to the proxy handler, TAPI has already returned a positive dwRequestID function result to the original application and unblocked the calling thread to continue execution. The application is awaiting a LINE_REPLY message, which is automatically generated when the proxy handler application calls lineProxyResponse.

The application shall not free the memory pointed to by lpProxyRequest. TAPI frees the memory during the execution of lineProxyResponse. The application can call lineProxyResponse exactly once for each LINE_PROXYREQUEST message.

If the application receives a LINE_CLOSE message while it has pending proxy requests, it should call lineProxyResponse for each pending request, passing in an appropriate dwResult value (such as LINEERR_OPERATIONFAILED).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CLOSE, LINE_REPLY, LINEPROXYREQUEST, lineProxyResponse


LINE_PROXYSTATUS

The LINE_QUEUESTATUS message is sent when the available proxies change on a line that the application currently has open.

TAPISRV generates this message during a lineOpen function using LINEPROXYSTATUS_OPEN and LINEPROXYSTATUS_ALLOPENFORACD or a lineClose function using LINEPROXYSTATUS_CLOSE (all LINEPROXYSTATUS_ Constants).

LINE_PROXYSTATUS
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) QueueID;
dwParam2 = (DWORD) QueueStatus;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
The application's handle to the line device. This relates to the agent handler.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Specifies the queue status that has changed. Can be one or more of the LINEPROXYSTATUS_ constants.
dwParam2
If dwParam1 is set to LINEPROXYSTATUS_OPEN or LINEPROXYSTATUS_CLOSE, dwParam2 indicates the related proxy request type, which is one of the following:

LINEPROXYREQUEST_SETAGENTGROUP LINEPROXYREQUEST_SETAGENTSTATE LINEPROXYREQUEST_SETAGENTACTIVITY LINEPROXYREQUEST_GETAGENTCAPS LINEPROXYREQUEST_GETAGENTSTATUS LINEPROXYREQUEST_AGENTSPECIFIC LINEPROXYREQUEST_GETAGENTACTIVITYLIST LINEPROXYREQUEST_GETAGENTGROUPLIST LINEPROXYREQUEST_CREATEAGENT LINEPROXYREQUEST_SETAGENTMEASUREMENTPERIOD LINEPROXYREQUEST_GETAGENTINFO LINEPROXYREQUEST_CREATEAGENTSESSION LINEPROXYREQUEST_GETAGENTSESSIONLIST LINEPROXYREQUEST_SETAGENTSESSIONSTATE LINEPROXYREQUEST_GETAGENTSESSIONINFO LINEPROXYREQUEST_GETQUEUELIST LINEPROXYREQUEST_SETQUEUEMEASUREMENTPERIOD LINEPROXYREQUEST_GETQUEUEINFO LINEPROXYREQUEST_GETGROUPLIST LINEPROXYREQUEST_SETAGENTSTATEEX

Otherwise, dwParam2 is set to zero.

dwParam3
Reserved. Set to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineOpen, lineClose, LINE_PROXYREQUEST, LINEPROXYREQUEST_ Constants


LINE_QUEUESTATUS

The LINE_QUEUESTATUS message is sent when the status of an ACD queue changes on an agent handler for which the application currently has an open line. This message is generated using the lineProxyMessage function.

LINE_QUEUESTATUS
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) QueueID;
dwParam2 = (DWORD) QueueStatus;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
The application's handle to the line device. This relates to the agent handler.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The identifier of the queue whose status has changed.
dwParam2
Specifies the queue status that has changed. Can be one or more of the LINEQUEUESTATUS_ constants.
dwParam3
Reserved. Set to zero.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.

See Also

About TAPI 3.0 Call Center Controls, lineProxyMessage


Formatted Error Messages

The following formatted error message is used with TAPI.

TAPIERROR_FORMATMESSAGE


TAPIERROR_FORMATMESSAGE

The TAPIERROR_FORMATMESSAGE macro generates an identifier for standard TAPI error message text strings that can be obtained by Win32 applications using the Win32 FormatMessage function.

This mechanism should be used only for displaying information on errors for which the application has no defined method of recovery (that is, unexpected or internal errors). In most cases (unlike the following simplified example), it is desirable to include additional text informing the user of actions the application takes (or the user should take) as a result of the unhandled error.

If the application gets an error result from any TAPI function, the error value can be passed through the TAPIERROR_FORMATMESSAGE macro, which in turn generates the real value to be passed to FormatMessage. FormatMessage produces an error string corresponding to the error in a buffer. For example:

lResult = lineClose(hLine);

if (lResult < 0)
{
        FormatMessage(FORMAT_MESSAGE_FROM_HMODULE,
                    (LPCVOID)GetModuleHandle("TAPIUI.DLL"),
                    TAPIERROR_FORMATMESSAGE(lResult),
                    0,
                    (LPTSTR)pBuf,
                    BUFSIZE,
                    NULL);
        MessageBox(hWnd,pBuf,"TAPI ERROR",MB_OK);
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


Line Device Messages

This section contains the reference for the following line device messages:

  • LINE_ADDRESSSTATE
  • LINE_APPNEWCALL
  • LINE_APPNEWCALLHUB
  • LINE_CALLINFO
  • LINE_CALLHUBCLOSE
  • LINE_CALLSTATE
  • LINE_CLOSE
  • LINE_CREATE
  • LINE_DEVSPECIFIC
  • LINE_DEVSPECIFICEX
  • LINE_DEVSPECIFICFEATURE
  • LINE_GATHERDIGITS
  • LINE_GENERATE
  • LINE_LINEDEVSTATE
  • LINE_MONITORDIGITS
  • LINE_MONITORMEDIA
  • LINE_MONITORTONE
  • LINE_REMOVE
  • LINE_REPLY
  • LINE_REQUEST


LINE_ADDRESSSTATE

The TAPI LINE_ADDRESSSTATE message is sent when the status of an address changes on a line that is currently open by the application. The application can invoke lineGetAddressStatus to determine the current status of the address.

LINE_ADDRESSSTATE
hDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idAddress;
dwParam2 = (DWORD) AddressState;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the line device.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The address identifier of the address that changed status.
dwParam2
The address state that changed. Can be one or more of the LINEADDRESSSTATE_ constants.
dwParam3
Unused.

Return Values

No return value.

Remarks

The LINE_ADDRESSSTATE message is sent to any application that has opened the line device and that has enabled this message. The sending of this message for the various status items can be controlled and queried using lineGetStatusMessages and lineSetStatusMessages. By default, address status reporting is disabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEADDRESSCAPS, lineGetAddressCaps, lineGetAddressStatus, lineGetStatusMessages, lineSetStatusMessages


LINE_APPNEWCALL

The TAPI LINE_APPNEWCALL message is sent to inform an application when a new call handle has been spontaneously created on its behalf (other than through an API call from the application, in which case the handle would have been returned through a pointer parameter passed into the function).

LINE_APPNEWCALL
hDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) dwAddressID;
dwParam2 = (DWORD) hCall;
dwParam3 = (DWORD) dwPrivilege;

Parameters

hDevice
The application's handle to the line device on which the call has been created.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
Identifier of the address on the line on which the call appears. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwParam2
The application's handle to the new call.
dwParam3
The applications privilege to the new call (LINECALLPRIVILEGE_OWNER or LINECALLPRIVILEGE_MONITOR).

Return Values

No return value.

Remarks and Backward Compatibility

Applications supporting TAPI version 2.0 or later are sent a LINE_APPNEWCALL message whenever the application is spontaneously given a handle to a new call. Because the message includes the hLine and dwAddressID parameters on which the call exists, the application can readily create a new call object in the correct context. The LINE_APPNEWCALL message is always immediately followed by a LINE_CALLSTATE message indicating the initial state of the call.

Older applications (that negotiated an API version earlier than 2.0) are sent only a LINE_CALLSTATE message, as documented in previous versions of the API. Such applications would create a new call object upon receiving a LINE_CALLSTATE message that has dwParam3 set to a nonzero value and containing a call handle not presently known by the application. The disadvantages are that (a) the application must call lineGetCallInfo to determine the hLine and dwAddressID parameters associated with the call; (b) the application must scan all known call handles to determine that the call is a new call; and (c) it is possible, under certain conditions, for the application to think it is receiving a new call handle when in reality it has just deallocated its handle to the call (for example, the application has just deallocated a call handle, but a LINE_CALLSTATE message giving the application ownership of the call due to a lineHandoff from another application was already in the application's TAPI message queue).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLSTATE, lineGetCallInfo, lineHandoff


LINE_APPNEWCALLHUB

The TAPI LINE_APPNEWCALLHUB message is sent to inform an application when a new call hub has been created.

LINE_APPNEWCALLHUB
hDevice = (DWORD) hCall;
dwCallbackInstance = dwCallbackInstance;
dwParam1 = (DWORD) CallHubTracking;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The tracking level on the new hub, as defined by one of the LINECALLHUBTRACKING_ Constants.

Return Values

No return value.

Remarks

This message originates with TAPI rather than with a service provider, so there is no corresponding TSPI message.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi.h.


LINE_CALLINFO

The TAPI LINE_CALLINFO message is sent when the call information about the specified call has changed. The application can invoke lineGetCallInfo to determine the current call information.

LINE_CALLINFO
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) CallInfoState;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The call information item that has changed. Can be one or more of the LINECALLINFOSTATE_ constants.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

A LINE_CALLINFO message with a NumOwnersIncr, NumOwnersDecr, and/or NumMonitorsChanged indication is sent to applications that already have a handle for the call. This can be the result of another application changing ownership or monitorship to a call with lineOpen, lineClose, lineShutdown, lineSetCallPrivilege, lineGetNewCalls, and lineGetConfRelatedCalls.

These LINE_CALLINFO messages are not sent when a notification of a new call is provided in a LINE_CALLSTATE message, because the call information already reflects the correct number of owners and monitors at the time the LINE_CALLSTATE messages are sent. LINE_CALLINFO messages are also suppressed in the case where a call is offered by TAPI to monitors through the LINECALLSTATE_UNKNOWN mechanism.

Note The application that causes a change in the number of owners or monitors (for example, by invoking lineDeallocateCall or lineSetCallPrivilege) does not itself receive a message indicating that the change has been done.

No LINE_CALLINFO messages are sent for a call after the call has entered the idle state. Specifically, changes in the number of owners and monitors are not reported as applications deallocate their handles for the idle call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineClose, lineDeallocateCall, lineGetCallInfo, lineGetConfRelatedCalls, lineGetNewCalls, lineOpen, lineSetCallPrivilege, lineShutdown


LINE_CALLHUBCLOSE

The TAPI LINE_CALLHUBCLOSE message is sent when a call hub has been closed.

LINE_CALLHUBCLOSE
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) dwCallbackInstance;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
Reserved. Set to 0.
dwParam2
Reserved. Set to 0.
dwParam3
Reserved. Set to 0.

Return Values

No return value.

Remarks

This message originates with TAPI rather than with a service provider, so there is no corresponding TSPI message.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi.h.


LINE_CALLSTATE

The TAPI LINE_CALLSTATE message is sent when the status of the specified call has changed. Typically, several such messages are received during the lifetime of a call. Applications are notified of new incoming calls with this message; the new call is in the offering state. The application can use lineGetCallStatus to retrieve more detailed information about the current status of the call.

LINE_CALLSTATE
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) CallState;
dwParam2 = (DWORD) CallStateDetail;
dwParam3 = (DWORD) CallPrivilege;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The new call state. This parameter must be one and only one of the following LINECALLSTATE_ constants.
dwParam2
Call-state-dependent information.
dwParam1 | dwParam2
If dwParam1 is LINECALLSTATE_BUSY, | dwParam2 contains details about the busy mode. This parameter uses one of the LINEBUSYMODE_ constants.
If dwParam1 is LINECALLSTATE_CONNECTED, | dwParam2 contains details about the connected mode. This parameter uses one of the LINECONNECTEDMODE_ constants.
If dwParam1 is LINECALLSTATE_DIALTONE, | dwParam2 contains details about the dial tone mode. This parameter uses one of the LINEDIALTONEMODE_ constants.
If dwParam1 is LINECALLSTATE_OFFERING, | dwParam2 contains details about the connected mode. This parameter uses one of the LINEOFFERINGMODE_ constants.
If dwParam1 is LINECALLSTATE_SPECIALINFO, | dwParam2 contains the details about the special information mode. This parameter uses one of the LINESPECIALINFO_ constants.
If dwParam1 is LINECALLSTATE_DISCONNECTED, | dwParam2 contains details about the disconnect mode. This parameter uses one of the LINEDISCONNECTMODE_ constants.

Note In circumstances where a delayed response is appropriate, use LINEDISCONNECTMODE_TEMPFAILURE. Where a blacklisted response is appropriate, use LINEDISCONNECT_BLOCKED. For further information, see LINEDISCONNECTMODE_ Constants.

If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the hConfCall parameter of the parent call of the conference of which the subject hCall is a member. If the call specified in dwParam2 was not previously considered by the application to be a parent conference call (hConfCall), the application must do so as a result of this message. If the application does not have a handle to the parent call of the conference (because it has previously called lineDeallocateCall on that handle) dwParam2 is set to NULL.

dwParam3
If zero, this parameter indicates that there has been no change in the application's privilege for the call.

If nonzero, it specifies the application's privilege for the call. This occurs in the following situations: (1) The first time that the application is given a handle to this call; (2) When the application is the target of a call handoff (even if the application already was an owner of the call). This parameter uses one of the following LINECALLPRIVILEGE_ constants.

Return Values

No return value.

Remarks

This message is sent to any application that has a handle for the call. The LINE_CALLSTATE message also notifies applications that monitor calls on a line about the existence and state of outbound calls established by other applications or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which is not offering. By examining the call state, the application can determine whether the call is an inbound call that needs to be answered or not.

A LINE_CALLSTATE message with an unknown call state can be sent to a monitoring application as the result of a successful lineMakeCall, lineForward, lineUnpark, lineSetupTransfer, linePickup, lineSetupConference, or linePrepareAddToConference that has been requested by another application. At the same time that the requesting application is sent a LINE_REPLY (success) for the requested operation, any monitoring applications on the line are sent the LINE_CALLSTATE (unknown) message. A LINE_CALLSTATE message indicating the "real" call state of the newly generated call is sent (using information provided by the service provider) to the requesting and monitoring applications shortly thereafter.

A LINE_CALLSTATE (unknown) message is sent to monitoring applications only if lineCompleteTransfer causes calls to be resolved into a three-way conference.

For backward compatibility, older applications are not expecting any particular value in dwParam2 of a LINECALLSTATE_CONFERENCED message. TAPI therefore passes the parent call hConfCall in dwParam2 regardless of the API version of the application receiving the message. In the case of a conference call initiated by the service provider, the older application is not aware that the parent call has become a conference call unless it happens to spontaneously examine other information (for example, call lineGetConfRelatedCalls).

This message cannot be disabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_REPLY, lineCompleteTransfer, lineDeallocateCall, LINEDIALPARAMS, lineForward, lineGenerateDigits, lineGetCallStatus, lineGetConfRelatedCalls, lineMakeCall, linePickup, linePrepareAddToConference, lineSetupTransfer, lineUnpark


LINE_CLOSE

The TAPI LINE_CLOSE message is sent when the specified line device has been forcibly closed. The line device handle or any call handles for calls on the line are no longer valid once this message has been sent.

LINE_CLOSE
hDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the line device that was closed. This handle is no longer valid.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

The LINE_CLOSE message is only sent to any application after an open line has been forcibly closed. This can be done to prevent a single application from monopolizing a line device for too long. Whether or not the line can be reopened immediately after a forced close is device-specific.

A line device can also be forcibly closed after the user has modified the configuration of that line or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), then a service provider can forcibly close the line device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINE_CREATE

The TAPI LINE_CREATE message is sent to inform the application of the creation of a new line device.

LINE_CREATE
hDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) idDevice;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
Unused.
dwCallbackInstance
Unused.
dwParam1
The hDeviceID of the newly created device.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

Older applications (that negotiated TAPI version 1.3) are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REINIT, which requires them to shut down their use of the API and call lineInitialize again to obtain the new number of devices. Unlike previous versions of TAPI, however, this version does not require all applications to shut down before allowing applications to reinitialize; reinitialization can take place immediately when a new device is created (complete shutdown is still required when a service provider is removed from the system).

Applications supporting TAPI version 1.4 or later are sent a LINE_CREATE message. This informs them of the existence of the new device and its new device identifier. The application can then choose whether or not to attempt working with the new device at its leisure. This message is sent to all applications supporting this or subsequent versions of the API that have called lineInitialize or lineInitializeEx, including those that do not have any line devices open at the time.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx


LINE_DEVSPECIFIC

The TAPI LINE_DEVSPECIFIC message is sent to notify the application about device-specific events occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.

LINE_DEVSPECIFIC
hDevice = (DWORD) hLineOrCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

hDevice
A handle to either a line device or call. This is device specific.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

No return value.

Remarks

The LINE_DEVSPECIFIC message is used by a service provider in conjunction with the lineDevSpecific function. Its meaning is device specific.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINE_DEVSPECIFICEX

The TAPI LINE_DEVSPECIFICEX message is sent to notify the application about device-specific events occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.

LINE_DEVSPECIFICEX
hDevice = (DWORD) hLineOrCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

hDevice
A handle to either a line device or call. This parameter is device specific.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

No return value.

Remarks

The LINE_DEVSPECIFICEX message is used by a service provider in conjunction with the lineDevSpecific function. Its meaning is device specific.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi.h.


LINE_DEVSPECIFICFEATURE

The TAPI LINE_DEVSPECIFICFEATURE message is sent to notify the application about device-specific events occurring on a line, address, or call. The meaning of the message and the interpretation of the parameters are device specific.

LINE_DEVSPECIFICFEATURE
hDevice = (DWORD) hLineOrCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

hDevice
A handle to either a line device or call. This is device specific.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

No return value.

Remarks

The LINE_DEVSPECIFICFEATURE message is used by a service provider in conjunction with the lineDevSpecificFeature function. Its meaning is device specific.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINE_GATHERDIGITS

The TAPI LINE_GATHERDIGITS message is sent when the current buffered digit-gathering request has terminated or is canceled. The digit buffer can be examined after this message has been received by the application.

LINE_GATHERDIGITS
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) GatherTermination;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The reason why digit gathering was terminated. This parameter must be one and only one of the LINEGATHERTERM_ constants.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the digit gathering completed. For TAPI versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_GATHERDIGITS message is only sent to the application that initiated the digit gathering on the call using lineGatherDigits.

If the lineGatherDigits function is used to cancel a previous request to gather digits, TAPI sends a LINE_GATHERDIGITS message with dwParam1 set to LINEGATHERTERM_CANCEL to the application indicating that the originally specified buffer contains the digits gathered up to the cancellation.

Because the timestamp specified by dwParam3 may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

Note When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a LINE_REPLY or LINE_GATHERDIGITS message is received.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE, LINE_REPLY, lineGatherDigits


LINE_GENERATE

The TAPI LINE_GENERATE message is sent to notify the application that the current digit or tone generation has terminated. Only one such generation request can be in progress an a given call at any time. This message is also sent when digit or tone generation is canceled.

LINE_GENERATE
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) GenerateTermination;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The reason why digit or tone generation was terminated. This parameter must be one and only one of the LINEGENERATETERM_ constants.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the digit or tone generation completed. For API versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_GENERATE message is only sent to the application that requested the digit or tone generation.

Because the timestamp specified by dwParam3 may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE


LINE_LINEDEVSTATE

The TAPI LINE_LINEDEVSTATE message is sent when the state of a line device has changed. The application can invoke lineGetLineDevStatus to determine the new status of the line.

LINE_LINEDEVSTATE
hDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceState;
dwParam2 = (DWORD) DeviceStateDetail1;
dwParam3 = (DWORD) DeviceStateDetail2;

Parameters

hDevice
A handle to the line device. This parameter is NULL when dwParam1 is LINEDEVSTATE_REINIT.
dwCallbackInstance
The callback instance supplied when opening the line. If the dwParam1 parameter is LINEDEVSTATE_REINIT, the dwCallbackInstance parameter is not valid and is set to zero.
dwParam1
The line device status item that has changed. The parameter can be one or more of the LINEDEVSTATE_ constants.
dwParam2
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam2 contains the dwMsg parameter of the original message (for example, LINE_CREATE or LINE_LINEDEVSTATE). If dwParam2 is zero, this indicates that the REINIT message is a "real" REINIT message that requires the application to call lineShutdown at its earliest convenience.

dwParam3
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam3 contains the dwParam1 parameter of the original message (for example, LINEDEVSTATE_TRANSLATECHANGE or some other LINEDEVSTATE_ value, if dwParam2 is LINE_LINEDEVSTATE, or the new device identifier, if dwParam2 is LINE_CREATE).

Return Values

No return value.

Remarks

The sending of the LINE_LINEDEVSTATE message can be controlled with lineSetStatusMessages. An application can indicate status item changes about which it wants to be notified. By default, all status reporting is disabled except for LINEDEVSTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the line, including those that called lineOpen with the dwPrivileges parameter set to LINECALLPRIVILEGE_NONE, LINECALLPRIVILEGE_OWNER, LINECALLPRIVILEGE_MONITOR, or permitted combinations of these.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CLOSE, LINE_CREATE, LINEDEVCAPS, lineGetDevCaps, lineGetDevConfig, lineGetTranslateCaps, lineInitialize, lineOpen, lineSetStatusMessages, lineShutdown, LINETRANSLATECAPS, lineUncompleteCall


LINE_MONITORDIGITS

The TAPI LINE_MONITORDIGITS message is sent when a digit is detected. The sending of this message is controlled with the lineMonitorDigits function.

LINE_MONITORDIGITS
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) Digit;
dwParam2 = (DWORD) DigitMode;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The low-order byte contains the last digit received in a text representation.
dwParam2
The digit mode that was detected. This parameter must be one and only one of the LINEDIGITMODE_ constants.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the specified digit was detected. For TAPI versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORDIGITS message is sent to the application that has enabled digit monitoring.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORMEDIA, LINE_MONITORTONE, lineMonitorDigits


LINE_MONITORMEDIA

The TAPI LINE_MONITORMEDIA message is sent when a change in the call's media type is detected. The sending of this message is controlled with the lineMonitorMedia function.

LINE_MONITORMEDIA
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) MediaMode;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) TickCount;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The new media type (or mode). This parameter must be one and only one of the LINEMEDIAMODE_ constants.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the specified media was detected. For TAPI versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORMEDIA message is sent to the application that has enabled media monitoring for the media type detected.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE


LINE_MONITORTONE

The TAPI LINE_MONITORTONE message is sent when a tone is detected. The sending of this message is controlled with the lineMonitorTones function.

LINE_MONITORTONE
hDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) dwAppSpecific;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The application-specific dwAppSpecific member of the LINEMONITORTONE structure for the tone that was detected.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the tone was detected. For API versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORTONE message is only sent to the application that has requested the tone be monitored.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE, LINEMONITORTONE, lineMonitorTones


LINE_REMOVE

The TAPI LINE_REMOVE message is sent to inform an application of the removal (deletion from the system) of a line device. Generally, this is not used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were reinitialized.

LINE_REMOVE
hDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) hDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
Reserved. Set to zero.
dwCallbackInstance
Reserved. Set to zero.
dwParam1
Identifier of the line device that was removed.
dwParam2
Reserved. Set to zero.
dwParam3
Reserved. Set to zero.

Return Values

No return value.

Remarks and Backward Compatibility

Applications supporting TAPI version 2.0 or later are sent a LINE_REMOVE message. This informs them that the device has been removed from the system. The LINE_REMOVE message is preceded by a LINE_CLOSE message on each line handle, if the application had the line open. This message is sent to all applications supporting TAPI version 2.0 or later that have called lineInitializeEx, including those that do not have any line devices open at the time.

Older applications are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REMOVED, followed by a LINE_CLOSE message. Unlike the LINE_REMOVE message, however, these older applications can receive these messages only if they have the line open when it is removed. If they do not have the line open, their only indication that the device was removed would be receiving a LINEERR_NODEVICE error when they attempt to access the device.

After a device has been removed, any attempt to access the device by its device identifier results in a LINEERR_NODEVICE error. After all TAPI applications have shutdown so that TAPI can restart, and when TAPI is reinitialized, the removed device no longer occupies a device identifier.

Implementation Note It is TAPI that returns this LINEERR_NODEVICE; after a LINE_REMOVE message is received from a service provider; no further calls are made to that service provider using that line device identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, lineInitializeEx


LINE_REPLY

The TAPI LINE_REPLY message is sent to report the results of function calls that completed asynchronously.

LINE_REPLY
hDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idRequest;
dwParam2 = (DWORD) Status;
dwParam3 = (DWORD) 0;

Parameters

hDevice
Not used.
dwCallbackInstance
Returns the application's callback instance.
dwParam1
The request identifier for which this is the reply.
dwParam2
The success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.
dwParam3
Unused.

Return Values

No return value.

Remarks

Functions that operate asynchronously return a positive request identifier value to the application. This request identifier is returned with the reply message to identify the request that was completed. The other parameter for the LINE_REPLY message carries the success or failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled.

In some cases, an application may fail to receive the LINE_REPLY message corresponding to a call to an asynchronous function. This occurs if the corresponding call handle is deallocated before the message has been received.

Note When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a LINE_REPLY or LINE_GATHERDIGITS message is received.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_GATHERDIGITS


LINE_REQUEST

The TAPI LINE_REQUEST message is sent to report the arrival of a new request from another application.

LINE_REQUEST
hDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) hRegistration;
dwParam1 = (DWORD) RequestMode;
dwParam2 = (DWORD) RequestModeDetail1;
dwParam3 = (DWORD) RequestModeDetail2;

Parameters

hDevice
Not used.
dwCallbackInstance
The registration instance of the application specified on lineRegisterRequestRecipient.
dwParam1
The request mode of the newly pending request. This parameter uses the LINEREQUESTMODE_ constants.
dwParam2
If dwParam1 is set to LINEREQUESTMODE_DROP, dwParam2 contains the hWnd of the application requesting the drop. Otherwise, dwParam2 is unused.
dwParam3
If dwParam1 is set to LINEREQUESTMODE_DROP, the low-order word of dwParam3 contains the wRequestID as specified by the application requesting the drop. Otherwise, dwParam3 is unused.

Return Values

No return value.

Remarks

The LINE_REQUEST message is sent to the highest priority application that has registered for the corresponding request mode. This message indicates the arrival of an Assisted Telephony request of the specified request mode. If dwParam1 is LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL, the application can invoke lineGetRequest using the corresponding request mode to receive the request. If dwParam1 is LINEREQUESTMODE_DROP, the message contains all of the information the request recipient needs to perform the request.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineGetRequest, lineRegisterRequestRecipient, tapiRequestMakeCall


Phone Device Messages

This section contains the reference for the following phone device messages:

  • PHONE_BUTTON
  • PHONE_CLOSE
  • PHONE_CREATE
  • PHONE_DEVSPECIFIC
  • PHONE_REMOVE
  • PHONE_REPLY
  • PHONE_STATE


PHONE_BUTTON

The TAPI PHONE_BUTTON message is sent to notify the application that button press monitoring is enabled if it has detected a button press on the local phone.

PHONE_BUTTON
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idButtonOrLamp;
dwParam2 = (DWORD) ButtonMode;
dwParam3 = (DWORD) ButtonState;

Parameters

hPhone
A handle to the phone device.
dwCallbackInstance
The application's callback instance provided when opening the phone device.
dwParam1
The button/lamp identifier of the button that was pressed. Note that button identifiers zero through 11 are always the KEYPAD buttons, with '0' being button identifier zero, '1' being button identifier 1 (and so on through button identifier 9), and with '*' being button identifier 10, and '#' being button identifier 11. Additional information about a button identifier is available with phoneGetDevCaps and phoneGetButtonInfo.
dwParam2
The button mode of the button. This parameter uses one of the PHONEBUTTONMODE_ constants.
dwParam3
Specifies whether this is a button-down event or a button-up event. This parameter uses one of the PHONEBUTTONSTATE_ constants.

Return Values

No return value.

Remarks

A PHONE_BUTTON message is sent whenever a button changes state. An application is guaranteed that for each button down event, it is eventually sent a corresponding button up event. A service provider that is incapable of detecting the actual button up is required to generate the button up message shortly after the button down message for each button press.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

phoneGetButtonInfo, phoneGetDevCaps


PHONE_CLOSE

The TAPI PHONE_CLOSE message is sent when an open phone device has been forcibly closed as part of resource reclamation. The device handle is no longer valid once this message has been sent.

PHONE_CLOSE
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hPhone
A handle to the open phone device that was closed. The handle is no longer valid after this message has been sent.
dwCallbackInstance
The application's callback instance that provided when opening the phone device.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

The PHONE_CLOSE message is only sent to an application after an open phone has been forcibly closed. This can be done to prevent a single application from monopolizing a phone device for too long. Whether the phone can be reopened immediately after a forced close is device specific.

An open phone device can also be forcibly closed after the user has modified the configuration of that phone or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and these changes affect the application's current view of the device (such as a change in device capabilities), then a service provider can forcibly close the phone device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONE_CREATE

The TAPI PHONE_CREATE message is sent to inform applications of the creation of a new phone device.

PHONE_CREATE
hPhone = (HPHONE) hPhoneDev;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) idDevice;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hPhone
Unused.
dwCallbackInstance
Unused.
dwParam1
The hDeviceID of the newly created device.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

Applications that negotiated API version 1.3 are sent a PHONE_STATE message specifying PHONESTATE_REINIT, which requires them to shut down their use of the API and call phoneInitialize again to obtain the new number of devices. However, TAPI version 1.4 and above do not require all applications to shut down before allowing applications to reinitialize; reinitialization can take place immediately when a new device is created.

Applications supporting TAPI version 1.4 or later are sent a PHONE_CREATE message. This informs them of the existence of the new device and its new device identifier. The application can then choose whether or not to attempt working with the new device at its leisure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONE_STATE, phoneInitialize, phoneInitializeEx


PHONE_DEVSPECIFIC

TAPI sends the PHONE_DEVSPECIFIC message to an application to notify the application about device-specific events occurring at the phone. The meaning of the message and the interpretation of the parameters is implementation-defined.

PHONE_DEVSPECIFIC
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

hPhone
A handle to the phone device.
dwCallbackInstance
The application's callback instance provided when opening the phone device.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

No return value.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONE_REMOVE

The TAPI PHONE_REMOVE message is sent to inform an application of the removal (deletion from the system) of a phone device. Generally, this is not used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were reinitialized.

PHONE_REMOVE
hDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) hDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hDevice
Reserved. Set to zero.
dwCallbackInstance
Reserved. Set to zero.
dwParam1
Identifier of the phone device that was removed.
dwParam2
Reserved. Set to zero.
dwParam3
Reserved. Set to zero.

Return Values

No return value.

Remarks and Backward Compatibility

Applications TAPI version 2.0 or later are sent a PHONE_REMOVE message. This informs them that the device has been removed from the system. The PHONE_REMOVE message is preceded by a PHONE_CLOSE message on each phone handle, if the application had the phone open. This message is sent to all applications supporting TAPI version 2.0 or later that have called phoneInitializeEx, including those that do not have any phone devices open at the time.

Older applications (that negotiated TAPI version 1.4 or earlier) are sent a PHONE_STATE message specifying PHONESTATE_REMOVED, followed by a PHONE_CLOSE message. Unlike the PHONE_REMOVE message, however, these older applications can receive these messages only if they have the phone open when it is removed. If they do not have the phone open, their only indication that the device was removed would be receiving a PHONEERR_NODEVICE when they attempt to access the device.

After a device has been removed, any attempt to access the device by its device identifier results in a PHONEERR_NODEVICE error. After all TAPI applications have shutdown so that TAPI can restart, and when TAPI is reinitialized, the removed device no longer occupies a device identifier.

Implementation Note It is TAPI that returns this PHONEERR_NODEVICE message after a PHONE_REMOVE message is received from a service provider; no further calls are made to that service provider using that phone device identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONE_CLOSE, PHONE_STATE, phoneInitialize, phoneInitializeEx


PHONE_REPLY

The TAPI PHONE_REPLY message is sent to an application to report the results of function call that completed asynchronously.

PHONE_REPLY
hPhone = (HPHONE) 0;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idRequest;
dwParam2 = (DWORD) Status;
dwParam3 = (DWORD) 0;

Parameters

hPhone
Unused.
dwCallbackInstance
Returns the application's callback instance.
dwParam1
The request identifier for which this is the reply.
dwParam2
The success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.
dwParam3
Unused.

Return Values

No return value.

Remarks

Functions that operate asynchronously return a positive request identifier value to the application. This request identifier is returned with the reply message to identify the request that was completed. The other parameter for the PHONE_REPLY message carries the success or failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONE_STATE

TAPI sends the PHONE_STATE message to an application whenever the status of a phone device changes.

PHONE_STATE
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) PhoneState;
dwParam2 = (DWORD) PhoneStateDetails;
dwParam3 = (DWORD) 0;

Parameters

hPhone
A handle to the phone device.
dwCallbackInstance
The application's callback instance provided when opening the phone device.
dwParam1
The phone state that has changed. This parameter uses one of the PHONESTATE_ constants.
dwParam2
Phone state-dependent information detailing the status change. This parameter is not used if multiple flags are set in dwParam1, because multiple status items have changed. The application should invoke phoneGetStatus to obtain a complete set of information.

If dwParam1 is PHONESTATE_OWNER, dwParam2 contains the new number of owners.

If dwParam1 is PHONESTATE_MONITORS, dwParam2 contains the new number of monitors.

If dwParam1 is PHONESTATE_LAMP, dwParam2 contains the button/lamp identifier of the lamp that has changed.

If dwParam1 is PHONESTATE_RINGMODE, dwParam2 contains the new ring mode.

If dwParam1 is PHONESTATE_HANDSET, SPEAKER or HEADSET, dwParam2 contains the new hookswitch mode of that hookswitch device. This parameter uses one of the PHONEHOOKSWITCHMODE_ constants.

dwParam3
Unused.

Return Values

No return value.

Remarks

Sending the PHONE_STATE message to the application can be controlled and queried using phoneSetStatusMessages and phoneGetStatusMessages. By default, this message is disabled for all state changes except for PHONESTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the phone, including those that called phoneOpen with the dwPrivileges parameter set to PHONEPRIVILEGE_OWNER or PHONEPRIVILEGE_MONITOR.

A PHONE_STATE message with an Owners and/or Monitors indication is sent to applications that already have a handle for the phone. This can be the result of another application changing ownership or monitorship of the phone device with phoneOpen, phoneClose or phoneShutdown.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONE_CLOSE, PHONECAPS, phoneClose, phoneGetDevCaps, phoneGetStatus, phoneGetStatusMessages, phoneInitialize, phoneInitializeEx, phoneOpen, phoneSetStatusMessages, phoneShutdown


TAPI Constants

This section contains the reference for the following TAPI constants:

Call Center Constants

Line Device Constants

Phone Device Constants

TAPIERR_ Constants


Call Center Constants

This section contains reference material for the following Call Center constants:

LINEAGENTFEATURE_ Constants

LINEAGENTSESSIONSTATE_ Constants

LINEAGENTSESSIONSTATUS_ Constants

LINEAGENTSTATE_ Constants

LINEAGENTSTATEEX_ Constants

LINEAGENTSTATUS_ Constants

LINEAGENTSTATUSEX_ Constants

LINEGROUPSTATUS_ Constants

LINEPROXYREQUEST_ Constants

LINEPROXYSTATUS_ Constants

LINEQUEUESTATUS_ Constants


LINEAGENTFEATURE_ Constants

The LINEAGENTFEATURE_ constants list features that are available for an agent on an address.

LINEAGENTFEATURE_AGENTSPECIFIC
The lineAgentSpecific function can be invoked on this address.
LINEAGENTFEATURE_GETAGENTACTIVITYLIST
The lineGetAgentActivityList function can be invoked on this address.
LINEAGENTFEATURE_GETAGENTGROUP
The lineGetAgentGroupList function can be invoked on this address.
LINEAGENTFEATURE_SETAGENTACTIVITY
The lineSetAgentActivity function can be invoked on this address.
LINEAGENTFEATURE_SETAGENTGROUP
The lineSetAgentGroup function can be invoked on this address.
LINEAGENTFEATURE_SETAGENTSTATE
The lineSetAgentState function can be invoked on this address.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEAGENTSESSIONSTATE_ Constants

The LINEAGENTSESSIONSTATE_ constants describe various agent session states.

LINEAGENTSESSIONSTATE_BUSYONCALL
The agent is busy handling a call.
LINEAGENTSESSIONSTATE_BUSYWRAPUP
The agent is busy handling the wrap-up of the call.
LINEAGENTSESSIONSTATE_ENDED
The agent session has ended.
LINEAGENTSESSIONSTATE_NOTREADY
The agent is logged in, but occupied with a task other than serving a call (such as on a break). No additional calls should be routed to the agent.
LINEAGENTSESSIONSTATE_READY
The agent is ready to accept calls.
LINEAGENTSESSIONSTATE_RELEASED
The agent session has been released.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.


LINEAGENTSESSIONSTATUS_ Constants

The LINEAGENTSESSIONSTATUS_ constants describe various agent session states.

LINEAGENTSESSIONSTATUS_NEWSESSION
A new agent session has been created.
LINEAGENTSESSIONSTATUS_STATE
Status of the current agent session.
LINEAGENTSESSIONSTATUS_UPDATEINFO
Update of the current agent session statistics

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.


LINEAGENTSTATE_ Constants

The LINEAGENTSTATE_ constants describe the state of an agent on an address.

LINEAGENTSTATE_BUSYACD
The agent is busy handling a call routed from an ACD queue.
LINEAGENTSTATE_BUSYINCOMING
The agent is busy handling an incoming call that was not transferred to the agent from an ACD queue in which the agent is logged in.
LINEAGENTSTATE_BUSYOTHER
The agent is busy handling another type of call, such as an outgoing personal call not transferred to the agent by a predictive dialer. This value can also be used when the agent is known to be busy on a call but the type of call is unknown.
LINEAGENTSTATE_BUSYOUTBOUND
The agent is busy handling an outgoing call, such as one routed from a predictive dialing queue.
LINEAGENTSTATE_LOGGEDOFF
No agent is logged in on the address.
LINEAGENTSTATE_NOTREADY
The agent is logged in, but occupied with a task other than serving a call (such as on a break). No additional calls should be routed to the agent.
LINEAGENTSTATE_READY
The agent is ready to accept calls.
LINEAGENTSTATE_UNAVAIL
The agent state is unknown and will never become known. In LINEADDRESSSTATUS, this condition can also be represented by the dwAgentState member being set to 0.
LINEAGENTSTATE_UNKNOWN
The agent state is currently unknown, but may become known later. This can be a transitional state when a line or address is first opened.
LINEAGENTSTATE_WORKINGAFTERCALL
The agent has completed the preceding call, but is still occupied with work related to that call. The agent should not receive additional calls.

The upper 16 bits of this set of constants are reserved for device-specific extensions.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEAGENTSTATEEX_ Constants

The LINEAGENTSTATEEX_ constants describe the state of an agent on an address.

LINEAGENTSTATEEX_BUSYACD
The agent is busy handling a call routed from an ACD queue.
LINEAGENTSTATEEX_BUSYINCOMING
The agent is busy handling an incoming call that was not transferred to the agent from an ACD queue in which the agent is logged in.
LINEAGENTSTATEEX_BUSYOUTGOING
The agent is busy handling an outgoing call, such as one routed from a predictive dialing queue.
LINEAGENTSTATEEX_NOTREADY
The agent is logged in, but occupied with a task other than serving a call (such as on a break). No additional calls should be routed to the agent.
LINEAGENTSTATEEX_READY
The agent is ready to accept calls.
LINEAGENTSTATEEX_RELEASED
The agent has been released, probably because they logged off.
LINEAGENTSTATEEX_UNKNOWN
The agent state is currently unknown, but may become known later. This can be a transitional state when a line or address is first opened.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.


LINEAGENTSTATUS_ Constants

The LINEAGENTSTATUS_ constants list the update status of the members of the LINEAGENTSTATUS structure for an agent.

LINEAGENTSTATUS_ACTIVITY
The dwActivityID, dwActivitySize, or dwActivityOffset member in LINEAGENTSTATUS has been updated.
LINEAGENTSTATUS_ACTIVITYLIST
The LINEAGENTACTIVITYLIST has been updated. The application can call lineGetAgentActivityList to get the updated list.
LINEAGENTSTATUS_CAPSCHANGE
The capabilities in LINEAGENTCAPS have been updated. The application can call lineGetAgentCaps to get the updated list.
LINEAGENTSTATUS_GROUP
The LINEAGENTSTATUS has been updated.
LINEAGENTSTATUS_GROUPLIST
The LINEAGENTGROUPLIST has been updated. The application can call lineGetAgentGroupList to get the updated list.
LINEAGENTSTATUS_NEXTSTATE
The dwNextState member in LINEAGENTSTATUS has been updated.
LINEAGENTSTATUS_STATE
The dwState member in LINEAGENTSTATUS has been updated.
LINEAGENTSTATUS_VALIDNEXTSTATES
The dwValidNextStates member in LINEAGENTSTATUS has been updated.
LINEAGENTSTATUS_VALIDSTATES
The dwValidStates member in LINEAGENTSTATUS has been updated.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEAGENTACTIVITYLIST, LINEAGENTCAPS, LINEAGENTGROUPLIST, LINEAGENTSTATUS, lineGetAgentActivityList, lineGetAgentCaps, lineGetAgentGroupList


LINEAGENTSTATUSEX_ Constants

The LINEAGENTSTATUSEX_ constants describe the status of an agent.

LINEAGENTSTATUSEX_NEWAGENT
An agent has been added.
LINEAGENTSTATUSEX_STATE
The current agent status.
LINEAGENTSTATUSEX_UPDATEINFO
The agent status has updated information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.


LINEGROUPSTATUS_ Constants

The LINEGROUPSTATUS_ constants specify the ACD group status.

LINEGROUPSTATUS_GROUPREMOVED
This group has been removed from the list of those available.
LINEGROUPSTATUS_NEWGROUP
A group has been added to the list of those available.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.


LINEPROXYREQUEST_ Constants

These constants are used in two contexts. First, they can be used in an array of DWORD values in the LINECALLPARAMS structure passed in with lineOpen when the LINEOPENOPTION_PROXY option is specified, to indicate which functions the application is willing to handle. Second, they are used in the LINEPROXYREQUEST passed to the handler application by a LINE_PROXYREQUEST message to indicate the type of request that is to be processed and the format of the data in the buffer.

LINEPROXYREQUEST_AGENTSPECIFIC
Associated with lineAgentSpecific.
LINEPROXYREQUEST_CREATEAGENT
Associated with lineCreateAgent.
LINEPROXYREQUEST_CREATEAGENTSESSION
Associated with lineCreateAgentSession.
LINEPROXYREQUEST_GETAGENTACTIVITYLIST
Associated with lineGetAgentActivityList.
LINEPROXYREQUEST_GETAGENTCAPS
Associated with lineGetAgentCaps.
LINEPROXYREQUEST_GETAGENTGROUPLIST
Associated with lineGetAgentGroupList.
LINEPROXYREQUEST_GETAGENTINFO
Associated with lineGetAgentInfo.
LINEPROXYREQUEST_GETAGENTSESSIONINFO
Associated with lineGetAgentSessionInfo.
LINEPROXYREQUEST_GETAGENTSESSIONLIST
Associated with lineGetAgentSessionList.
LINEPROXYREQUEST_GETAGENTSTATUS
Associated with lineGetAgentStatus.
LINEPROXYREQUEST_GETGROUPLIST
Associated with lineGetGroupList.
LINEPROXYREQUEST_GETQUEUEINFO
Associated with lineGetQueueInfo.
LINEPROXYREQUEST_GETQUEUELIST
Associated with lineGetQueueList.
LINEPROXYREQUEST_SETAGENTACTIVITY
Associated with lineSetAgentActivity.
LINEPROXYREQUEST_SETAGENTGROUP
Associated with lineSetAgentGroup.
LINEPROXYREQUEST_SETAGENTMEASUREMENTPERIOD
Associated with lineSetAgentMeasurementPeriod.
LINEPROXYREQUEST_SETAGENTSESSIONSTATE
Associated with lineSetAgentSessionState.
LINEPROXYREQUEST_SETAGENTSTATE
Associated with lineSetAgentState.
LINEPROXYREQUEST_SETAGENTSTATEEX
Associated with lineSetAgentStateEx.
LINEPROXYREQUEST_SETQUEUEMEASUREMENTPERIOD
Associated with lineSetQueueMeasurementPeriod.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

Call Center Constants, Call Center Functions


LINEPROXYSTATUS_ Constants

The LINEPROXYSTATUS_ constants indicate the status of the proxy on a line that the application currently has open.

See LINEPROXYREQUEST_ Constants for a list and description of all possible proxy request values.

LINEPROXYSTATUS_ALLOPENFORACD
The line now has proxies open for all the proxy request types required for ACD operations by TAPI version 3.0.
LINEPROXYSTATUS_CLOSE
A proxy has closed.
LINEPROXYSTATUS_OPEN
A new proxy has opened.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.


LINEQUEUESTATUS_ Constants

The LINEQUEUESTATUS_ constants indicate the change in status of an ACD queue on an agent handler.

LINEQUEUESTATUS_NEWQUEUE
A queue has been added to those available.
LINEQUEUESTATUS_QUEUEREMOVED
This queue has been removed from those available.
LINEQUEUESTATUS_UPDATEINFO
Update of information about the ACD queue.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 2.2 or later.
Header: Declared in Tapi.h.


Line Device Constants

This section contains an alphabetic listing of the following TAPI line device constants:

  • LINEADDRCAPFLAGS_ Constants
  • LINEADDRESSMODE_ Constants
  • LINEADDRESSSHARING_ Constants
  • LINEADDRESSSTATE_ Constants
  • LINEADDRFEATURE_ Constants
  • LINEANSWERMODE_ Constants
  • LINEBEARERMODE_ Constants
  • LINEBUSYMODE_ Constants
  • LINECALLCOMPLCOND_ Constants
  • LINECALLCOMPLMODE_ Constants
  • LINECALLFEATURE_ Constants
  • LINECALLFEATURE2_ Constants
  • LINECALLHUBTRACKING_ Constants
  • LINECALLINFOSTATE_ Constants
  • LINECALLORIGIN_ Constants
  • LINECALLPARAMFLAGS_ Constants
  • LINECALLPARTYID_ Constants
  • LINECALLPRIVILEGE_ Constants
  • LINECALLREASON_ Constants
  • LINECALLTREATMENT_ Constants
  • LINECALLSELECT_ Constants
  • LINECALLSTATE_ Constants
  • LINECARDOPTION_ Constants
  • LINECONNECTEDMODE_ Constants
  • LINEDEVCAPFLAGS_ Constants
  • LINEDEVSTATE_ Constants
  • LINEDEVSTATUSFLAGS_ Constants
  • LINEDIALTONEMODE_ Constants
  • LINEDIGITMODE_ Constants
  • LINEDISCONNECTMODE_ Constants
  • LINEERR_ Constants
  • LINEFEATURE_ Constants
  • LINEFORWARDMODE_ Constants
  • LINEGATHERTERM_ Constants
  • LINEGENERATETERM_ Constants
  • LINELOCATIONOPTION_ Constants
  • LINEINITIALIZEEXOPTION_ Constants
  • LINEMEDIACONTROL_ Constants
  • LINEMEDIAMODE_ Constants
  • LINEOFFERINGMODE_ Constants
  • LINEOPENOPTION_ Constants
  • LINEPARKMODE_ Constants
  • LINEREMOVEFROMCONF_ Constants
  • LINEREQUESTMODE_ Constants
  • LINEROAMMODE_ Constants
  • LINESPECIALINFO_ Constants
  • LINETERMDEV_ Constants
  • LINETERMMODE_ Constants
  • LINETERMSHARING_ Constants
  • LINETOLLLISTOPTION_ Constants
  • LINETONEMODE_ Constants
  • LINETRANSFERMODE_ Constants
  • LINETRANSLATEOPTION_ Constants
  • LINETRANSLATERESULT_ Constants
  • LINETSPIOPTION_ Constants


LINEADDRCAPFLAGS_ Constants

The LINEADDRCAPFLAGS_ bit-flag constants are used in the dwAddrCapFlags member of the LINEADDRESSCAPS data structure to describe various Boolean address capabilities.

LINEADDRCAPFLAGS_ACCEPTTOALERT
TRUE if an offering call must be accepted using lineAccept to start alerting the users at both ends of the call; otherwise, FALSE. This is typically only used with ISDN.
LINEADDRCAPFLAGS_ACDGROUP
The address supports ACD Groups in connection with call center operations. See About TAPI 3.0 Call Center Controls for additional information on ACD groups.
LINEADDRCAPFLAGS_AUTORECONNECT
Specifies whether dropping a consultation call automatically reconnects to the call on consultation hold. TRUE if reconnect happens automatically; otherwise, FALSE.
LINEADDRCAPFLAGS_BLOCKIDDEFAULT
Specifies whether the network by default sends or blocks caller ID information when making a call on this address. If TRUE, identifier information is blocked by default; if FALSE, identifier information is transmitted by default.
LINEADDRCAPFLAGS_BLOCKIDOVERRIDE
Specifies whether the default setting for sending or blocking of caller ID information can be overridden per call. If TRUE, override is possible; if FALSE, override is not possible.
LINEADDRCAPFLAGS_COMPLETIONID
Specifies whether the completion identifiers returned by lineCompleteCall are useful and unique. TRUE if useful; otherwise, FALSE.
LINEADDRCAPFLAGS_CONFDROP
TRUE if lineDrop on a conference call parent also has the side effect of dropping (that is, disconnecting) the other parties involved in the conference call; FALSE if dropping a conference call still allows the other parties to talk among themselves.
LINEADDRCAPFLAGS_CONFERENCEHELD
Specifies whether a hard-held call can be conferenced to. Often, only calls on consultation hold can be added to as a conference call.
LINEADDRCAPFLAGS_CONFERENCEMAKE
Specifies whether an entirely new call can be established for use as a consultation call (to add) on conference.
LINEADDRCAPFLAGS_DESTOFFHOOK
Specifies whether the called party's phone can automatically be forced offhook when making calls.
LINEADDRCAPFLAGS_DIALED
Specifies whether a destination address can be dialed on this address for making a call. TRUE if a destination address must be dialed; FALSE if the destination address is fixed (as with a "hot phone").
LINEADDRCAPFLAGS_FWDBUSYNAADDR
Specifies whether call forwarding for busy and for no answer can use different forwarding addresses. This flag is meaningful only if forwarding for busy and for no answer can be controlled separately. This flag is TRUE if forwarding for busy and for no answer can use different destination addresses; otherwise, it is FALSE.
LINEADDRCAPFLAGS_FWDCONSULT
Specifies whether call forwarding involves the establishment of a consultation call.
LINEADDRCAPFLAGS_FWDINTEXTADDR
Specifies whether internal and external calls can be forwarded to different forwarding addresses. This flag is meaningful only if forwarding of internal and external calls can be controlled separately. This flag is TRUE if internal and external calls can be forwarded to different destination addresses; otherwise, it is FALSE.
LINEADDRCAPFLAGS_FWDNUMRINGS
Specifies whether the number of rings for a no-answer can be specified when forwarding calls on no answer. If TRUE, the valid range is provided in the dwMinFwdNumRings and dwMaxFwdNumRings members of the LINEADDRESSCAPS structure.
LINEADDRCAPFLAGS_FWDSTATUSVALID
Specifies whether the forwarding status in the LINEADDRESSSTATUS structure for this address is valid or is at most a "best estimate," given absence of accurate confirmation by the switch or network.
LINEADDRCAPFLAGS_HOLDMAKESNEW
When a call on this address is placed on hold (using lineHold or external action), a new call is automatically created (most likely in LINECALLSTATE_DIALTONE).
LINEADDRCAPFLAGS_NOEXTERNALCALLS
The address is associated with an internal line on a PBX that is restricted in such a way that it cannot be used to place calls to an address outside the switch (for example, it is an intercom). The application can use this indication to assist the user in selecting the correct call appearance to use for making a call. When this bit is off, it does not necessarily indicate that the address can be used to make external calls, because the service provider may not be cognizant of the line type.
LINEADDRCAPFLAGS_NOINTERNALCALLS
The address is associated with a direct CO line (trunk), and cannot be used to make internal calls on a PBX. The application can use this indication to assist the user in selecting the correct call appearance to use for making a call. When this bit is off, it does not necessarily indicate that the address can be used to make internal calls, because the service provider may not be cognizant of the line type.
LINEADDRCAPFLAGS_NOPSTNADDRESSTRANSLATION
This address does not support public switched telephone network address translation. This flag is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINEADDRCAPFLAGS_ORIGOFFHOOK
Specifies whether the originating party's phone can automatically be taken offhook when making calls.
LINEADDRCAPFLAGS_PARTIALDIAL
Specifies whether partial dialing is available.
LINEADDRCAPFLAGS_PICKUPCALLWAIT
TRUE if linePickup can be used to pick up a call detected by the user as a call-waiting call; otherwise, FALSE.
LINEADDRCAPFLAGS_PICKUPGROUPID
Specifies whether a group identifier is required for call pickup.
LINEADDRCAPFLAGS_PREDICTIVEDIALER
This address has enhanced call progress monitoring capabilities which can be applied to outgoing calls to determine call states such as ringback, busy, specialinfo, and connected, or the media type of the device answering the call. It may also have the ability to automatically transfer outgoing calls to another address when a call reaches any of a predefined set of states.
LINEADDRCAPFLAGS_QUEUE
This address is not associated with a particular station or physical device, but is a holding place where calls wait for further processing. The calls placed in the queue may receive a particular treatment. They may also be automatically transferred when a particular resource becomes available (for example, if the queue is an ACD queue and calls are waiting for an available agent).
LINEADDRCAPFLAGS_ROUTEPOINT
This address is not associated with a particular station or physical device, but is a holding place where calls wait for routing by the application (the application examines the called address, and can redirect the call to another address). The call can also be automatically transferred if a routing timeout expires (the switch usually assumes a default routing).
LINEADDRCAPFLAGS_SECURE
Specifies whether calls on this address can be made secure at call-setup time.
LINEADDRCAPFLAGS_SETCALLINGID
The application can choose to set the CallingPartyID member in LINECALLPARAMS when calling lineMakeCall and other functions that accept a LINECALLPARAMS structure. The service provider will, if the content of the identifier is acceptable and a path is available, pass the identifier along to the called party to indicate the identity of the calling party.
LINEADDRCAPFLAGS_SETUPCONFNULL
Specifies whether setting up a conference call starts out with an initial call (FALSE) or with no initial call (TRUE).
LINEADDRCAPFLAGS_TRANSFERHELD
Specifies whether a hard-held call can be transferred. Often, only calls on consultation hold can be transferred.
LINEADDRCAPFLAGS_TRANSFERMAKE
Specifies whether an entirely new call can be established for use as a consultation call on transfer.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineAccept, LINEADDRESSCAPS, LINEADDRESSSTATUS, LINECALLPARAMS, lineCompleteCall, lineDrop, lineHold, lineMakeCall, linePickup


LINEADDRESSMODE_ Constants

The LINEADDRESSMODE_ bit-flag constants describe various ways of identifying an address on a line device.

LINEADDRESSMODE_ADDRESSID
The address is specified with a small integer in the range 0 to dwNumAddresses minus one, where dwNumAddresses is the value in the line's device capabilities.
LINEADDRESSMODE_DIALABLEADDR
The address is specified through its phone number.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

This constant is used to select an address on a line on which to originate a call. The usual model would select the address by means of its address identifier. Address identifiers are the mechanism used to identify addresses throughout TAPI. However, in some environments, when making a call, it is often more practical to identify a call's originating address by phone number rather than by address identifier. One example is in the possible modeling of large numbers of stations (third party) on the switch by means of one line device with many addresses. The line represents the set of all stations, and each station is mapped to an address with its own primary phone number and address identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEADDRESSSHARING_ Constants

The LINEADDRESSSHARING_ bit-flag constants describe various ways an address can be shared between lines.

LINEADDRESSSHARING_PRIVATE
The address is private to the user's line; it is not assigned to any other station.
LINEADDRESSSHARING_BRIDGEDEXCL
The address is bridged to one or more other stations. The first line to activate a call on the line will have exclusive access to the address and calls that may exist on it. Other lines will not be able to use the bridged address while it is in use.
LINEADDRESSSHARING_BRIDGEDNEW
The address is bridged with one or more other stations. The first line to activate a call on the line will have exclusive access to only the corresponding call. Other applications that use the address will result in new and separate call appearances.
LINEADDRESSSHARING_BRIDGEDSHARED
The address is bridged with one or more other lines. All bridged parties can share in calls on the address, which then functions as a conference.
LINEADDRESSSHARING_MONITORED
This is an address whose idle/busy status is made available to this line.

No extensibility. All 32 bits are reserved.

The way in which an address is shared across lines can affect the behavior of that address. LINE_CALLSTATE and LINE_ADDRESSSTATE messages are sent to the application in response to activities by the bridging stations. It is through these messages that an application can track the status of the address.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_ADDRESSSTATE, LINE_CALLSTATE


LINEADDRESSSTATE_ Constants

The LINEADDRESSSTATE_ bit-flag constants describe various address status items.

LINEADDRESSSTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINEADDRESSCAPS structure for the address have changed. The application should use lineGetAddressCaps to read the updated structure. If a service provider sends a LINE_ADDRESSSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shut down and reinitialize their connection to TAPI to obtain the updated information.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed, including possibly the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being in use by more than one station.
LINEADDRESSSTATE_INUSEONE
The address has changed from idle or in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is not in use by any stations).
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of events such as a new incoming call, an outgoing call on the address, or a call changing its hold status. This flag covers changes in any of the members dwNumActiveCalls, dwNumOnHoldCalls and dwNumOnHoldPendingCalls in the LINEADDRESSSTATUS structure. The application should check all three of these members when it receives a LINE_ADDRESSSTATE (numCalls) message.
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.

No extensibility. All 32 bits are reserved.

An application is notified about changes to these status items in the LINE_ADDRESSSTATE message. The address's device capabilities indicate which address state changes can possibly be reported for this address.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_ADDRESSSTATE, LINE_LINEDEVSTATE, LINEADDRESSCAPS, LINEADDRESSSTATUS, lineGetAddressCaps


LINEADDRFEATURE_ Constants

The LINEADDRFEATURE_ constants list the operations that can be invoked on an address.

LINEADDRFEATURE_FORWARD
The address can be forwarded.
LINEADDRFEATURE_MAKECALL
An outgoing call can be placed on the address.
LINEADDRFEATURE_PICKUP
A call can be picked up at the address.
LINEADDRFEATURE_PICKUPDIRECT
The linePickup function can be used to pick up a call on a specific address.
LINEADDRFEATURE_PICKUPGROUP
The linePickup function can be used to pick up a call in the group.
LINEADDRFEATURE_PICKUPHELD
The linePickup function (with a null destination address) can be used to pick up a call that is held on the address. This is normally used only in a bridged-exclusive arrangement.
LINEADDRFEATURE_PICKUPWAITING
The linePickup function (with a null destination address) can be used to pick up a call waiting call. Note that this does not necessarily indicate that a waiting call is actually present, because it is often impossible for a telephony device to automatically detect such a call; it does, however, indicate that the hook-flash function will be invoked to attempt to switch to such a call.
LINEADDRFEATURE_SETMEDIACONTROL
Media control can be set on this address.
LINEADDRFEATURE_SETTERMINAL
The terminal modes for this address can be set.
LINEADDRFEATURE_SETUPCONF
A conference call with a NULL initial call can be set up at this address.
LINEADDRFEATURE_UNCOMPLETECALL
Call completion requests can be canceled at this address.
LINEADDRFEATURE_UNPARK
Calls can be unparked using this address.

Note If none of the new modified "PICKUP" bits is set in the dwAddressFeatures member in LINEADDRESSSTATUS but the LINEADDRFEATURE_PICKUP bit is set, then any of the pickup modes may work; the service provider has simply not specified which ones.

LINEADDRFEATURE_FORWARDDND
The lineForward function (with an empty destination address) can be used to turn on the Do Not Disturb feature on the address. LINEADDRFEATURE_FORWARD will also be set.
LINEADDRFEATURE_FORWARDFWD
The lineForward function can be used to forward calls on the address to other numbers. LINEADDRFEATURE_FORWARD will also be set.

Note If neither of the new modified "FORWARD" bits is set in the dwAddressFeatures member in LINEADDRESSSTATUS but the LINEADDRFEATURE_FORWARD bit is set, then any of the forward modes may work; the service provider has simply not specified which ones.

No extensibility. All 32 bits are reserved.

This constant is used both in LINEADDRESSCAPS (returned by lineGetAddressCaps) and in LINEADDRESSSTATUS (returned by lineGetAddressStatus). LINEADDRESSCAPS reports the availability of the address features by the service provider (mainly the switch) for a given address. An application would make this determination when it initializes. The LINEADDRESSSTATUS structure reports, for a given address, which address features can actually be invoked while the address is in the current state. An application would make this determination dynamically after address-state changes, typically caused by call-related activities on the address.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEADDRESSCAPS, LINEADDRESSSTATUS, lineForward, lineGetAddressCaps, lineGetAddressStatus, linePickup


LINEANSWERMODE_ Constants

The LINEANSWERMODE_ bit-flag constants describe how an existing active call on a line device is affected by answering another offering call on the same line.

LINEANSWERMODE_DROP
The currently active call will automatically be dropped.
LINEANSWERMODE_HOLD
The currently active call will automatically be placed on hold.
LINEANSWERMODE_NONE
Answering another call on the same line has no effect on the existing active call on the line.

No extensibility. All 32 bits are reserved.

If a call comes in (is offered) at the time another call is already active, the new call is connected to by invoking lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEBEARERMODE_ Constants

The LINEBEARERMODE_ bit-flag constants describe different bearer modes of a call. When an application makes a call, it can request a specific bearer mode. These modes are used to select a certain quality of service for the requested connection from the underlying telephone network. Bearer modes available on a given line are a device capability of the line.

LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_NONCALLSIGNALING
This corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by TAPI).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
LINEBEARERMODE_RESTRICTEDDATA
Bearer service for digital data in which only the low-order seven bits of each octet may contain user data (for example, for Switched 56kbit/s service).
LINEBEARERMODE_SPEECH
This corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media types.
LINEBEARERMODE_VOICE
This is a regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media types.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note that bearer mode and media type are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media type of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax or data modem are media types that use a call with a 3.1 kHz voice bearer mode.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEBUSYMODE_ Constants

The LINEBUSYMODE_ bit-flag constants describe different busy signals that the switch or network can generate. These busy signals typically indicate that a different resource that is required to make a call is currently in use.

LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled with a normal busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a fast busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown but may become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and will not become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note Busy signals can be sent as inband tones or out-of-band messages. TAPI makes no assumption about the specific signaling mechanism.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLCOMPLCOND_ Constants

The LINECALLCOMPLCOND_ bit-flag constants describe the conditions under which a call can be completed.

LINECALLCOMPLCOND_BUSY
Completion of the call under busy conditions.
LINECALLCOMPLCOND_NOANSWER
Completion of the call under ringback no answer conditions.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLCOMPLMODE_ Constants

The LINECALLCOMPLMODE_ bit-flag constants describe different ways in which a call can be completed.

LINECALLCOMPLMODE_CALLBACK
Requests the called station to return the call when it returns to idle.
LINECALLCOMPLMODE_CAMPON
Queues the call until the call can be completed.
LINECALLCOMPLMODE_INTRUDE
Adds the application to the existing call at the called station (barge in).
LINECALLCOMPLMODE_MESSAGE
Leaves a short predefined message for the called station (Leave Word Calling). The message to be sent is specified separately.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLFEATURE_ Constants

The LINECALLFEATURE_ constants indicate operations that can be invoked for a given address or call.

LINECALLFEATURE_ACCEPT
Accept the call (lineAccept).
LINECALLFEATURE_ADDTOCONF
Add the call to the current conference (lineAddToConference).
LINECALLFEATURE_ANSWER
Answer the call (lineAnswer).
LINECALLFEATURE_BLINDTRANSFER
Perform a blind transfer on the call (lineBlindTransfer).
LINECALLFEATURE_COMPLETECALL
Complete the call (lineCompleteCall).
LINECALLFEATURE_COMPLETETRANSF
Complete the call transfer (lineCompleteTransfer).
LINECALLFEATURE_DIAL
Dial the destination number for the call (lineDial).
LINECALLFEATURE_DROP
Drop the call (lineDrop).
LINECALLFEATURE_GATHERDIGITS
Gather digits from the call (lineGatherDigits).
LINECALLFEATURE_GENERATEDIGITS
Generate digits on the call (lineGenerateDigits).
LINECALLFEATURE_GENERATETONE
Generate tones on the call (lineGenerateTone).
LINECALLFEATURE_HOLD
Put the call on hold (lineHold).
LINECALLFEATURE_MONITORDIGITS
Monitor digits on the call (lineMonitorDigits ).
LINECALLFEATURE_MONITORMEDIA
Monitor the call's media (lineMonitorMedia).
LINECALLFEATURE_MONITORTONES
Monitor tones on the call (lineMonitorTones).
LINECALLFEATURE_PARK
Park the call (linePark).
LINECALLFEATURE_PREPAREADDCONF
Prepare the call for addition to a conference (linePrepareAddToConference).
LINECALLFEATURE_REDIRECT
Redirect the call to another destination (lineRedirect).
LINECALLFEATURE_RELEASEUSERUSERINFO
Release current user-user information (lineReleaseUserUserInfo).
LINECALLFEATURE_REMOVEFROMCONF
Remove the call from the conference (lineRemoveFromConference).
LINECALLFEATURE_SECURECALL
Secure the call (lineSecureCall).
LINECALLFEATURE_SENDUSERUSER
Send user-user information (lineSendUserUserInfo).
LINECALLFEATURE_SETCALLDATA
Set the call data buffer (lineSetCallData). (TAPI versions 2.0 and later).
LINECALLFEATURE_SETCALLPARAMS
Set call parameters (lineSetCallParams).
LINECALLFEATURE_SETMEDIACONTROL
Set media controls (lineSetMediaControl).
LINECALLFEATURE_SETQOS
Set QOS levels for the call (lineSetCallQualityOfService). (TAPI versions 2.0 and later).
LINECALLFEATURE_SETTERMINAL
Set the terminal to be used with the call (lineSetTerminal).
LINECALLFEATURE_SETTREATMENT
Set call treatment (lineSetCallTreatment). (TAPI versions 2.0 and later).
LINECALLFEATURE_SETUPCONF
Set up a conference (lineSetupConference).
LINECALLFEATURE_SETUPTRANSFER
Set up a transfer (lineSetupTransfer).
LINECALLFEATURE_SWAPHOLD
Perform a swap hold operation (lineSwapHold).
LINECALLFEATURE_UNHOLD
Take the call off hold (lineUnhold).

No extensibility. All 32 bits are reserved.

These constants are used both in LINEADDRESSCAPS (returned by lineGetAddressCaps) and in LINECALLSTATUS (returned by lineGetCallStatus). LINEADDRESSCAPS reports the availability of the call features on the specified address. An application would use this information when it initializes to determine what it may be able to do later when calls exist. For the specified call, LINECALLSTATUS reports which call features can be invoked while the call is in the current call state. The latter takes call privileges into account. An application would make this determination dynamically, after call state changes.

The LINECALLFEATURE_RELEASEUSERUSERINFO value is new to TAPI 1.4. There are no backward compatibility considerations. A service provider may elect to return this value in relevant members (in LINEADDRESSCAPS and LINECALLSTATUS) even when older API versions have been negotiated on the line device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEADDRESSCAPS, LINECALLSTATUS, lineGetAddressCaps, lineGetCallStatus


LINECALLFEATURE2_ Constants

The LINECALLFEATURE2_ constants list the supplemental features available for conferencing, transferring, and parking calls.

LINECALLFEATURE2_COMPLCALLBACK
If this bit is on, the "callback" feature can be invoked by using the LINECOMPLMODE_CALLBACK option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_COMPLCAMPON
If this bit is on, the "camp on" feature can be invoked by using the LINECOMPLMODE_CAMPON option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_COMPLINTRUDE
If this bit is on, the "intrude" feature can be invoked by using the LINECOMPLMODE_INTRUDE option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_COMPLMESSAGE
If this bit is on, the "leave message" feature can be invoked by using the LINECOMPLMODE_MESSAGE option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_NOHOLDCONFERENCE
If this bit is on, a "no hold conference" can be created by using the LINECALLPARAMFLAGS_NOHOLDCONFERENCE option with lineSetupConference. The LINECALLFEATURE_SETUPCONF bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_ONESTEPTRANSFER
If this bit is on, "one step transfer" can be created by using the LINECALLPARAMFLAGS_ONESTEPTRANSFER option with lineSetupTransfer. The LINECALLFEATURE_SETUPTRANSFER bit will also be on in the dwCallFeatures member.

Note If none of the "COMPL" bits is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_COMPLETECALL is specified, then it is possible that any of them will work, but the service provider has not specified which.

LINECALLFEATURE2_TRANSFERCONF
If this bit is on, the lineCompleteTransfer function can be used to resolve the transfer as a three-way conference. The LINECALLFEATURE_COMPLETETRANSF bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_TRANSFERNORM
If this bit is on, the lineCompleteTransfer function can be used to resolve the transfer as a normal transfer. The LINECALLFEATURE_COMPLETETRANSF bit will also be on in the dwCallFeatures member.

Note If neither TRANSFERNORM nor TRANSFERCONF is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_COMPLETETRANSF is specified, then it is possible that either will work, but the service provider has not specified which.

LINECALLFEATURE2_PARKDIRECT
If this bit is on, the "directed park" feature can be invoked by using the LINEPARKMODE_DIRECTED option with linePark. The LINECALLFEATURE_PARK bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_PARKNONDIRECT
If this bit is on, the "non-directed park" feature can be invoked by using the LINEPARKMODE_NONDIRECTED option with linePark. The LINECALLFEATURE_PARK bit will also be on in the dwCallFeatures member.

Note If neither PARKDIRECT nor PARKNONDIRECT is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_PARK is specified, then it is possible that either will work, but the service provider has not specified which.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINECALLSTATUS, lineCompleteCall, lineCompleteTransfer, linePark, lineSetupConference, lineSetupTransfer


LINECALLHUBTRACKING_ Constants

The LINECALLHUBTRACKING_ bit-flag constants describe the type of call hub tracking provided.

LINECALLHUBTRACKING_ALLCALLS
Call hub tracking is provided at the call level.
LINECALLHUBTRACKING_NONE
No call hub tracking is provided.
LINECALLHUBTRACKING_PROVIDERLEVEL
Call hubs are tracked at the service provider level. Call by call changes are not reported.

No extensibility. All 32 bits are reserved.

When changes occur in this data structure, a LINE_CALLINFO message is sent to the application. The parameters to this message are a handle to the call and an indication of the information item that has changed. The LINECALLHUBTRACKINGINFO data structure indicates which tracking type is provided.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLINFO, LINECALLHUBTRACKINGINFO, LINECALLINFO


LINECALLINFOSTATE_ Constants

The LINECALLINFOSTATE_ bit-flag constants describe various call information items about which an application can be notified in the LINE_CALLINFO message.

LINECALLINFOSTATE_APPSPECIFIC
The application-specific field of the call-information record.
LINECALLINFOSTATE_BEARERMODE
The bearer mode field of the call-information record.
LINECALLINFOSTATE_CALLDATA
The CallData member in LINECALLINFO has been updated.
LINECALLINFOSTATE_CALLEDID
One of the calledID-related fields of the call-information record.
LINECALLINFOSTATE_CALLERID
One of the callerID-related fields of the call-information record.
LINECALLINFOSTATE_CALLID
The call ID field of the call-information record.
LINECALLINFOSTATE_CHARGINGINFO
The charging information of the call-information record.
LINECALLINFOSTATE_COMPLETIONID
The completion identifier field of the call-information record.
LINECALLINFOSTATE_CONNECTEDID
One of the connectedID-related fields of the call-information record.
LINECALLINFOSTATE_DEVSPECIFIC
The device-specific field of the call-information record.
LINECALLINFOSTATE_DIALPARAMS
The dial parameters of the call-information record.
LINECALLINFOSTATE_DISPLAY
The display field of the call-information record.
LINECALLINFOSTATE_HIGHLEVELCOMP
The high level compatibility field of the call-information record.
LINECALLINFOSTATE_LOWLEVELCOMP
The low level compatibility field of the call-information record.
LINECALLINFOSTATE_MEDIAMODE
The media type field of the call-information record.
LINECALLINFOSTATE_MONITORMODES
One or more of the digit, tone, or media monitoring fields in the call-information record.
LINECALLINFOSTATE_NUMMONITORS
The number of monitors field in the call-information record has changed.
LINECALLINFOSTATE_NUMOWNERDECR
The number of owner field in the call-information record was decreased.
LINECALLINFOSTATE_NUMOWNERINCR
The number of owner field in the call-information record was increased.
LINECALLINFOSTATE_ORIGIN
The origin field of the call-information record.
LINECALLINFOSTATE_OTHER
Call information items other than those listed below have changed. The application should check the current call information to determine which items have changed.
LINECALLINFOSTATE_QOS
One or more of the QOS members in LINECALLINFO has been updated.
LINECALLINFOSTATE_RATE
The rate field of the call-information record.
LINECALLINFOSTATE_REASON
The reason field of the call-information record.
LINECALLINFOSTATE_REDIRECTINGID
The address identifier of the location that redirected a call.
LINECALLINFOSTATE_REDIRECTIONID
The address identifier of the location to which a call has been redirected.
LINECALLINFOSTATE_RELATEDCALLID
The related call ID field of the call-information record.
LINECALLINFOSTATE_TERMINAL
The terminal mode information of the call-information record.
LINECALLINFOSTATE_TREATMENT
The CallTreatment member in LINECALLINFO has been updated. This can occur in response to a lineSetCallTreatment function, a call state change, a call "vector" or other script controlling the call, or upon completion of playback of a recorded message (ordinarily, indicating a change to "silence" or "music").
LINECALLINFOSTATE_TRUNK
The trunk field of the call-information record.
LINECALLINFOSTATE_USERUSERINFO
The user-user information of the call-information record.

No extensibility. All 32 bits are reserved.

When changes occur in this data structure, a LINE_CALLINFO message is sent to the application. The parameters to this message are a handle to the call and an indication of the information item that has changed. The LINEADDRESSCAPS data structure also indicates which of these call information elements are valid for every call on the address.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLINFO, LINEADDRESSCAPS, LINECALLINFO, lineSetCallTreatment


LINECALLORIGIN_ Constants

The LINECALLORIGIN_ constants describe the origin of a call.

LINECALLORIGIN_CONFERENCE
The call handle is for a conference call, that is, it is the application's connection to the conference bridge in the switch.
LINECALLORIGIN_EXTERNAL
The call originated as an incoming call on an external line.
LINECALLORIGIN_INBOUND
The call originated as an incoming call, but the service provider is unable to determine whether it came from another station on the same switch or from an external line. Service providers can use this constant only when TAPI version 1.4 or later has been negotiated. Otherwise, the service provider can substitute LINECALLORIGIN_UNAVAIL.
LINECALLORIGIN_INTERNAL
The call originated as an incoming call at a station internal to the same switching environment.
LINECALLORIGIN_OUTBOUND
The call originated from this station as an outgoing call.
LINECALLORIGIN_UNAVAIL
The call origin is not available and will never become known for this call.
LINECALLORIGIN_UNKNOWN
The call origin is currently unknown but may become known later.

No extensibility. All 32 bits are reserved.

The origin of a call is stored in the dwOrigin member of the call's LINECALLINFO structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLPARAMFLAGS_ Constants

The LINECALLPARAMFLAGS_ constants describe various status flags about a call.

LINECALLPARAMFLAGS_BLOCKID
The originator identity should be concealed (block caller ID).
LINECALLPARAMFLAGS_DESTOFFHOOK
The called party's phone should be automatically taken offhook.
LINECALLPARAMFLAGS_IDLE
The call should be originated on an idle call appearance and not join a call in progress. When using the lineMakeCall function, if the LINECALLPARAMFLAGS_IDLE value is not set and there is an existing call on the line, the function breaks into the existing call if necessary to make the new call. If there is no existing call, the function makes the new call as specified.
LINECALLPARAMFLAGS_NOHOLDCONFERENCE
This bit is used only in conjunction with lineSetupConference and linePrepareAddToConference. The address to be conferenced with the current call is specified in the TargetAddress member in LINECALLPARAMS. The consultation call does not physically draw dial tone from the switch, but will progress through various call establishment states (for example, dialing, proceeding). When the consultation call reaches the connected state, the conference is automatically established; the original call, which had remained in the connected state, enters the conferenced state; the consultation call enters the conferenced state; the hConfCall enters the connected state. If the consultation call fails (enters the disconnected state followed by idle), the hConfCall also enters the idle state, and the original call (which may have been an existing conference, in the case of linePrepareAddToConference) remains in the connected state. The original party (or parties) never perceive the call has having gone onhold. This feature is often used to add a supervisor to an ACD agent call when necessary to monitor interactions with an irate caller.
LINECALLPARAMFLAGS_ONESTEPTRANSFER
This bit is used only in conjunction with lineSetupTransfer. It combines the operation of lineSetupTransfer followed by lineDial on the consultation call into a single step. The address to be dialed is specified in the TargetAddress member in LINECALLPARAMS. The original call is placed in onholdpendingtranfer state, just as if lineSetupTransfer were called normally, and the consultation call is established normally. The application must still call lineCompleteTransfer to effect the transfer. This feature is often used when invoking a transfer from a server over a third-party call control link, because such links frequently do not support the normal two-step process.
LINECALLPARAMFLAGS_ORIGOFFHOOK
The originator's phone should be automatically taken offhook.
LINECALLPARAMFLAGS_PREDICTIVEDIAL
This bit is used only when placing a call on an address with predictive dialing capability (LINEADDRCAPFLAGS_PREDICTIVEDIALER is on in the dwAddrCapFlags member in LINEADDRESSCAPS). The bit must be on to enable the enhanced call progress and/or media device monitoring capabilities of the device. If this bit is not on, the call will be placed without enhanced call progress or media type monitoring, and no automatic transfer will be initiated based on call state.
LINECALLPARAMFLAGS_SECURE
The call should be set up as secure.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEADDRESSCAPS, LINECALLPARAMS, lineCompleteTransfer, lineDial, lineMakeCall, linePrepareAddToConference, lineSetupConference, lineSetupTransfer


LINECALLPARTYID_ Constants

The LINECALLPARTYID_ bit-flag constants describe the nature of the information available about the parties involved in a call.

LINECALLPARTYID_ADDRESS
Party identifier information consists of the party's address in either canonical address format or dialable address format.
LINECALLPARTYID_BLOCKED
Party identifier information is not available because it has been blocked by the remote party.
LINECALLPARTYID_NAME
Party identifier information consists of the party's name (as, for example, from a directory kept inside the switch).
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_PARTIAL
Party identifier information is valid but it is limited to partial information only.
LINECALLPARTYID_UNAVAIL
Party identifier information is not available and will not become available later. Information may be unavailable for unspecified reasons. For example, the information was not delivered by the network, it was ignored by the service provider, and so forth.
LINECALLPARTYID_UNKNOWN
Party identifier information is currently unknown but may become known later.

No extensibility. All 32 bits are reserved.

For each of the possible parties involved in a call, the LINECALLPARTYID_ constants describe how the party identifier information is formatted. This information is supplied in the LINECALLINFO data structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLPRIVILEGE_ Constants

The LINECALLPRIVILEGE_ bit-flag constants describe the kinds of access rights or privileges an application with a call handle may have to the corresponding call.

LINECALLPRIVILEGE_MONITOR
The application has monitor privileges to the call. These privileges allow the application to monitor state changes and query information and status about the call.
LINECALLPRIVILEGE_NONE
The application has no privileges to the call. The application's handle is void and should not be used.
LINECALLPRIVILEGE_OWNER
The application has owner privileges to the call. These privileges allow the application to manipulate the call in ways that affect the state of the call.

No extensibility. All 32 bits are reserved.

When a call handle is first provided to an application or whenever call privileges of that application are modified, the LINE_CALLSTATE message is sent to the application. When an application hands off a call, and if the receiving application does not already have a handle with owner privileges, then this message informs the application about its new privileges to the call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLREASON_ Constants

The LINECALLREASON_ bit-flag constants describe the reason for a call.

LINECALLREASON_CALLCOMPLETION
The call was the result of a call completion request.
LINECALLREASON_CAMPEDON
The call was camped on the address. Usually, it appears initially in the onhold state, and can be switched to using lineSwapHold. If an active call becomes idle, the camped-on call may change to the offering state and the device start ringing.
LINECALLREASON_DIRECT
This is a direct incoming or outgoing call.
LINECALLREASON_FWDBUSY
This call was forwarded from another extension that was busy at the time of the call.
LINECALLREASON_FWDNOANSWER
The call was forwarded from another extension that didn't answer the call after some number of rings.
LINECALLREASON_FWDUNCOND
The call was forwarded unconditionally from another number.
LINECALLREASON_INTRUDE
The call intruded onto the line, either by a call completion action invoked by another station or by operator action. Depending on switch implementation, the call may appear either in the connected state, or conferenced with an existing active call on the line.
LINECALLREASON_PARKED
The call was parked on the address. Usually, it appears initially in the onhold state.
LINECALLREASON_PICKUP
The call was picked up from another extension.
LINECALLREASON_REDIRECT
The call was redirected to this station.
LINECALLREASON_REMINDER
The call is a reminder (or "recall") that the user has a call parked or on hold for (potentially) a long time.
LINECALLREASON_ROUTEREQUEST
The call appears on the address because the switch needs routing instructions from the application. The application should examine the CalledID member in LINECALLINFO, and use the lineRedirect function to provide a new dialable address for the call. If the call is to be blocked instead, the application may call lineDrop. If the application fails to take action within a switch-defined timeout period, a default action will be taken. A service provider can use this constant only if the negotiated version on the line is 2.0 or higher. Otherwise the service provider should substitute LINECALLREASON_UNAVAIL.
LINECALLREASON_TRANSFER
The call has been transferred from another number.
LINECALLREASON_UNAVAIL
The reason for the call is unavailable and will not become known later.
LINECALLREASON_UNKNOWN
The reason for the call is currently unknown but may become known later.
LINECALLREASON_UNPARK
The call was retrieved as a parked call.

No extensibility. All 32 bits are reserved.

The LINECALLREASON_ constants are used in the dwReason member of the LINECALLINFO data structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINECALLINFO, lineDrop, lineRedirect, lineSwapHold


LINECALLTREATMENT_ Constants

The LINECALLTREATMENT_ constants list treatments for calls that are unanswered or on hold. Except for basic parameter validation, call treatment is a straight pass-through by TAPI to the service provider.

LINECALLTREATMENT_BUSY
When the call is not actively connected to a device (offering or onhold), the party hears busy signal.
LINECALLTREATMENT_MUSIC
When the call is not actively connected to a device (offering or onhold), the party hears music.
LINECALLTREATMENT_RINGBACK
When the call is not actively connected to a device (offering or onhold), the party hears ringback tone.
LINECALLTREATMENT_SILENCE
When the call is not actively connected to a device (offering or onhold), the party hears silence.

The value 0x00000000 is reserved to indicate that the service provider does not support call treatments. Values in the range 0x00000005 through 0x000000FF are reserved for future definition. Values in the range 0x00000100 through 0xFFFFFFFF are reserved for assignment by service providers, and may include identification of specific musical selections or recorded announcements.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLSELECT_ Constants

The LINECALLSELECT_ bit-flag constants describe which calls are to be selected.

LINECALLSELECT_ADDRESS
Selects call on the specified address.
LINECALLSELECT_CALL
Selects related calls to the specified call. For example, the parties in a conference call.
LINECALLSELECT_CALLID
Selects related calls to the specified call identifier. This flag is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINECALLSELECT_DEVICEID
Selects calls on the specified device identifier. This flag is exposed only to applications that negotiate a TAPI version of 2.1 or higher.
LINECALLSELECT_LINE
Selects calls on the specified line device.

No extensibility. All 32 bits are reserved.

This constant is used in lineGetNewCalls and to specify a selection (scope) of the calls that are requested.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECALLSTATE_ Constants

The LINECALLSTATE_ bit-flag constants describe the call states a call can be in.

LINECALLSTATE_ACCEPTED
The call was in the offering state and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, the accepted state is entered when the called-party equipment sends a message to the switch indicating that it is willing to present the call to the called person. This has the side effect of alerting (ringing) the users at both ends of the call. An incoming call can always be immediately answered without first being separately accepted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. A busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use. See LINEBUSYMODE_ Constants.
LINECALLSTATE_CONFERENCED
The call is a member of a conference call and is logically in the connected state.
LINECALLSTATE_CONNECTED
The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_DIALING
The originator is dialing digits on the call. The dialed digits are collected by the switch. Note that neither lineGenerateDigits nor TSPI_lineGenerateDigits will place the line into the dialing state.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number. See LINEDIALTONEMODE_ Constants for identifiers of special dial tones, such as a stutter tone of normal voice mail.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_IDLE
The call exists but has not been connected. No activity exists on the call, which means that no call is currently active. A call can never transition out of the idle state.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. The offering state is not the same as causing a phone or computer to ring. In some environments, a call in the offering state does not ring the user until the switch instructs the line to ring. An example use might be where an incoming call appears on several station sets but only the primary address rings. The instruction to ring does not affect any call states.
LINECALLSTATE_ONHOLD
The call is on hold by the switch. This frees the physical line, which allows another call to use the line.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network. This occurs after dialing is complete and before the call reaches the dialed party, as indicated by ringback, busy, or answer.
LINECALLSTATE_RINGBACK
The station to be called has been reached, and the destination's switch is generating a ring tone back to the originator. A ringback means that the destination address is being alerted to the call.
LINECALLSTATE_SPECIALINFO
The call is receiving a special information signal, which precedes a prerecorded announcement indicating why a call cannot be completed. See LINESPECIALINFO_ Constants.
LINECALLSTATE_UNKNOWN
The call exists, but its state is currently unknown. This may be the result of poor call progress detection by the service provider. A call state message with the call state set to unknown may also be generated to inform the TAPI DLL about a new call at a time when the actual call state of the call is not exactly known.

The high-order 8 bits can define a device-specific substate of any of the predefined states, provided that one of the LINECALLSTATE_ bits defined above is also set. The low-order 24 bits are reserved for predefined states.

The LINECALLSTATE_ constants are used as parameters by the LINE_CALLSTATE message sent to the application. The message carries the new call state that the call transitioned to. These constants are also used as members in the LINECALLSTATUS structure returned by the lineGetCallStatus function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLSTATE, LINECALLSTATUS, lineGenerateDigits, lineGetCallStatus


LINECARDOPTION_ Constants

The LINECARDOPTION_ constants define values used in the dwOptions member of the LINECARDENTRY structure returned as part of the LINETRANSLATECAPS structure returned by lineGetTranslateCaps. The LINECARDOPTION_ constant has the following values:

LINECARDOPTION_HIDDEN
This calling card has been hidden by the user. It is not shown by Dial Helper in the main listing of available calling cards, but will be shown in the list of cards from which dialing rules can be copied.
LINECARDOPTION_PREDEFINED
This calling card is one of the predefined calling card definitions included by Microsoft with Win32 Telephony. It cannot be removed entirely using Dial Helper; if the user attempts to remove it, it will become HIDDEN. It thus continues to be accessible for copying of dialing rules.

Not extensible. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINECONNECTEDMODE_ Constants

The LINECONNECTEDMODE_ bit-flag constants describe different substates of a connected call. A mode is available as call status to the application after the call state transitions to connected, and within the LINE_CALLSTATE message indicating the call is in LINECALLSTATE_CONNECTED. These values are used when the call is on an address that is shared (bridged) with other stations (see LINEADDRESSSHARING_ Constants), primarily electronic key systems. The LINECONNECTEDMODE_ constants have the following values:

LINECONNECTEDMODE_ACTIVE
Indicates that the call is connected at the current station (the current station is a participant in the call). If the call state mode is 0 (zero), the application should assume that the value is "active" (which would be the situation on a non-bridged address). The mode can switch between ACTIVE and INACTIVE during a call if the user joins and leaves the call through manual action. In such a bridged situation, a lineDrop or lineHold operation may possibly not actually drop the call or place it on hold, because the status of other stations on the call may govern (for example, attempting to "hold" a call when other stations are participating won't be possible); instead, the call may simply be changed to the INACTIVE mode if it remains CONNECTED at other stations.
LINECONNECTEDMODE_ACTIVEHELD
Indicates that the station is an active participant in the call, but that the remote party has placed the call on hold (the other party considers the call to be in the onhold state). Normally, such information is available only when both endpoints of the call fall within the same switching domain. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher. (TAPI versions 2.0 and later)
LINECONNECTEDMODE_CONFIRMED
Indicates that the service provider received affirmative notification that the call has entered the connected state (for example, through answer supervision or similar mechanisms). This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher. (TAPI versions 2.0 and later)
LINECONNECTEDMODE_INACTIVE
Indicates that the call is active at one or more other stations, but the current station is not a participant in the call. If the call state mode is ZERO, the application should assume that the value is "active" (which would be the situation on a non-bridged address). A call in the INACTIVE state can be joined using lineAnswer. Many operations that are valid in calls in the CONNECTED state can be impossible in the INACTIVE mode, such as monitoring for tones and digits, because the station is not actually participating in the call; monitoring is usually suspended (although not canceled) while the call is in the INACTIVE mode.
LINECONNECTEDMODE_INACTIVEHELD
Indicates that the station is not an active participant in the call, and that the remote party has placed the call on hold. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher. (TAPI versions 2.0 and later)

Not extensible. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use those LINECONNECTEDMODE_ values that are not supported on the negotiated version. Applications that are not cognizant of LINECONNECTEDMODE_ will most likely assume that a call that is in LINECALLSTATE_CONNECTED is in LINECONNECTEDMODE_ACTIVE.

The LINECONNECTEDMODE_ACTIVE and LINECONNECTEDMODE_INACTIVE values are used when the call is on an address that is shared with other stations (bridged; see LINEADDRESSSHARING_ Constants), primarily electronic key systems. If the connected call state mode is "active," it means that the call is connected at the current station (the current station is a participant in the call). If the call state mode is "inactive," the call is active at one or more other stations, but the current station is not a participant in the call. If the call state mode is ZERO, the application should assume that the value is "active" (which would be the situation on a non-bridged address). The mode can switch between ACTIVE and INACTIVE during a call if the user joins and leaves the call through manual action.

In such a bridged situation, a lineDrop or lineHold operation may possibly not actually drop the call or place it on hold, because the status of other stations on the call may govern (for example, attempting to "hold" a call when other stations are participating will not be possible); instead, the call can simply be changed to the INACTIVE mode if it remains connected at other stations. A call in the INACTIVE state can be joined using the lineAnswer.

Many operations that are valid in calls in the connected state can be impossible in the INACTIVE mode, such as monitoring for tones and digits, because the station is not actually participating in the call; monitoring is usually suspended (although not canceled) while the call is in the INACTIVE mode.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineAnswer, lineDrop, lineHold


LINEDEVCAPFLAGS_ Constants

The LINEDEVCAPFLAGS_ bit-flag constants are a collection of Booleans describing various line device capabilities.

LINEDEVCAPFLAGS_CALLHUB
Indicates whether call hubs are supported on this line. This flag is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINEDEVCAPFLAGS_CALLHUBTRACKING
Indicates whether call hub tracking is supported on this line. This flag is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINEDEVCAPFLAGS_CLOSEDROP
Specifies what happens when an open line is closed while the application has calls active on the line. If TRUE, the service provider drops (clears) all active calls on the line when the last application that has opened the line closes it with lineClose. If FALSE, the service provider does not drop active calls in such cases. Instead, the calls remain active and under control of external devices. A service provider typically sets this bit to FALSE if there is some other device that can keep the call alive, for example, if an analog line has the computer and phone set both connect directly to them in a party-line configuration, the offhook phone will automatically keep the call active even after the computer powers down.

Applications should check this flag to determine whether to warn the user (with an OK/Cancel dialog box) that active calls will be lost.

LINEDEVCAPFLAGS_CROSSADDRCONF
Specifies whether calls on different addresses on this line can be conferenced.
LINEDEVCAPFLAGS_DIALBILLING
LINEDEVCAPFLAGS_DIALDIALTONE
LINEDEVCAPFLAGS_DIALQUIET
These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; otherwise, FALSE. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine up front which modifiers would result in the generation of a LINEERR. The application has the choice of pre-scanning dialable strings for unsupported characters or of passing the "raw" string from lineTranslateAddress directly to the provider as part of functions such as lineMakeCall or lineDial and let the function generate an error to tell it which unsupported modifier occurs first in the string.
LINEDEVCAPFLAGS_HIGHLEVCOMP
Specifies whether high-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_LOWLEVCOMP
Specifies whether low-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_MEDIACONTROL
Specifies whether media-control operations are available for calls at this line.
LINEDEVCAPFLAGS_MSP
Indicates whether a Media Service Provider (MSP) is associated with the line. This flag is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINEDEVCAPFLAGS_MULTIPLEADDR
Specifies whether lineMakeCall, lineDial, TSPI_lineMakeCall, or TSPI_lineDial is able to deal with multiple addresses at once (as for inverse multiplexing).
LINEDEVCAPFLAGS_PRIVATEOBJECTS
Indicates whether provider-specific Interfaces have been implemented. This flag is exposed only to applications that negotiate a TAPI version of 3.0 or higher.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

lineClose, lineDial, lineMakeCall, lineTranslateAddress


LINEDEVSTATE_ Constants

The LINEDEVSTATE_ bit-flag constants describe various line status events.

LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shut down and reinitialize their connection to TAPI to obtain the updated information.
LINEDEVSTATE_CLOSE
The line has been closed by another application.
LINEDEVSTATE_CONFIGCHANGE
Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, can use lineGetDevConfig to read the updated information. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.
LINEDEVSTATE_COMPLCANCEL
Indicates that the call completion identified by the completion identifier contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in-service at the switch while TAPI is active.
LINEDEVSTATE_LOCK
The locked status of the line device has changed. (For more information, see LINEDEVSTATUSFLAGS_LOCKED in LINEDEVSTATUSFLAGS_ Constants.)
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MSGWAITOFF
The message waiting indicator is turned off.
LINEDEVSTATE_MSGWAITON
The message waiting indicator is turned on.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_OPEN
The line has been opened by another application.
LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (as for the appearance of new line devices) the application should reinitialize its use of TAPI.
LINEDEVSTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user.

TAPI: Service providers notify applications on each ring cycle by repeatedly sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.

TSPI: On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.

LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_TERMINALS
The terminal settings have changed. This can happen, for example, if multiple line devices share terminals among them (for example, two lines sharing a phone terminal).
LINEDEVSTATE_TRANSLATECHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shut down and reinitialize their connection to TAPI to obtain the updated information.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, LINEDEVCAPS, lineGetDevCaps, lineGetDevConfig, lineGetTranslateCaps, LINETRANSLATECAPS, lineUncompleteCall


LINEDEVSTATUSFLAGS_ Constants

The LINEDEVSTATUSFLAGS_ bit-flag constants describe a collection of Boolean line device status items.

LINEDEVSTATUSFLAGS_CONNECTED
Specifies whether the line is connected to TAPI. If TRUE, the line is connected and TAPI is able to operate on the line device. If FALSE, the line is disconnected and the application is unable to control the line device through TAPI.
LINEDEVSTATUSFLAGS_INSERVICE
Indicates whether the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.
LINEDEVSTATUSFLAGS_LOCKED
Indicates whether the line is locked or unlocked. This bit is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This bit can be used to indicate to applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone so that the application can present an appropriate alert to the user.
LINEDEVSTATUSFLAGS_MSGWAIT
Indicates whether the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.

No extensibility. All 32 bits are reserved.

LINEDEVSTATUSFLAGS_ constants are used within the dwDevStatusFlags member of the LINEDEVSTATUS data structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEDIALTONEMODE_ Constants

The LINEDIALTONEMODE_ bit-flag constants describe different types of dial tones. A special dial tone typically carries a special meaning (as with message waiting).

LINEDIALTONEMODE_EXTERNAL
This is an external (public network) dial tone.
LINEDIALTONEMODE_INTERNAL
This is an internal dial tone, as within a PBX.
LINEDIALTONEMODE_NORMAL
This is a normal dial tone, which typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
This is a special dial tone indicating that a certain condition (known by the switch or network) is currently in effect. Special dial tones typically use an interrupted tone. As with a normal dial tone, this indicates that the switch is ready to receive the number to be dialed.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and will not become known.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is not currently known but may become known later.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

The LINEDIALTONEMODE_ constants are used within the LINECALLSTATUS data structure for a call in the dialtone state.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEDIGITMODE_ Constants

The LINEDIGITMODE_ constants describe different types of inband digit generation.

LINEDIGITMODE_DTMF
Uses DTMF tones to signal digits. Valid digits are 0 through 9, '*', '#', 'A', 'B', 'C', and 'D'.
LINEDIGITMODE_DTMFEND
Uses DTMF tones to signal digits and detect the down edges. Valid digits are 0 through 9, '*', '#', 'A', 'B', 'C', and 'D'.
LINEDIGITMODE_PULSE
Uses rotary pulse sequences to signal digits. Valid digits are 0 through 9.

No extensibility. All 32 bits are reserved.

A digit mode can be specified when generating or detecting digits. Note that pulse digits are generated by making and breaking the local loop circuit. These pulses are absorbed by the switch. The remote end merely observes this as a series of inband audio clicks. Detecting digits sent as pulses must therefore be able to detect these sequences of 1 to 10 audible clicks.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEDISCONNECTMODE_ Constants

The LINEDISCONNECTMODE_ bit-flag constants describe different reasons for a remote disconnect request. A disconnect mode is available as call status to the application after the call state transitions to disconnected.

LINEDISCONNECTMODE_BADADDRESS
The destination address is invalid.
LINEDISCONNECTMODE_BLOCKED
The call could not be connected because calls from the origination address are not being accepted at the destination address. This differs from LINEDISCONNECTMODE_REJECT in that blocking is implemented in the network (a passive reject) while a rejection is implemented in the destination equipment (an active reject). The blocking can be due to a specific exclusion of the origination address, or because the destination accepts calls from only a selected set of origination address (closed user group). (TAPI versions 2.0 and later)

LINEDISCONNECTMODE_BLOCKED is appropriate as a blacklisted response. For example, a modem has received an answer, gone more than six seconds without detecting Ringback, failed to connect a defined number of times, determines that the phone number is not valid to call, and issues a 'blacklisted' response.

LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_CANCELLED
The call was cancelled. (TAPI versions 2.0 and later)
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_DONOTDISTURB
The call could not be connected because the destination has invoked the Do Not Disturb feature. (TAPI versions 2.0 and later)
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible with the type of call requested.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure. (TAPI versions 1.4 and later)
LINEDISCONNECTMODE_NORMAL
This is a normal disconnect request by the remote party. The call was terminated normally.
LINEDISCONNECTMODE_NUMBERCHANGED
The call could not be connected because the destination number has been changed, but automatic redirection to the new number is not provided. (TAPI versions 2.0 and later)
LINEDISCONNECTMODE_OUTOFORDER
The call could not be connected or was disconnected because the destination device is out of order (hardware failure). (TAPI versions 2.0 and later)
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_QOSUNAVAIL
The call could not be connected or was disconnected because the minimum quality of service could not be obtained or sustained. This differs from LINEDISCONNECTMODE_INCOMPATIBLE in that the lack of resources may be a temporary condition at the destination. (TAPI versions 2.0 and later)
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_TEMPFAILURE
The call could not be connected or was disconnected because of a temporary failure in the network; the call can be reattempted later and is expected to eventually complete. (TAPI versions 2.0 and later)

LINEDISCONNECTMODE_TEMPFAILURE is appropriate as a delayed response. For example, a modem getting a busy signal or equivalent too many times in a particular time period concludes that the number should not be called again until a defined time has elapsed and issues a 'delayed' response.

LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and will not become known later.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown but may become known later.
LINEDISCONNECTMODE_UNREACHABLE
The remote user could not be reached.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

A remote disconnect request for a given call results in the call state transitioning to the disconnected state and a LINE_CALLSTATE message is sent to the application. The LINEDISCONNECTMODE_ information provides details about the remote disconnect request. It is available in the call's LINECALLSTATUS structure when the call is in the disconnected state. While a call is in this state, the application is still allowed to query the call's information and status. For example, user-user information that is received as part of the remote disconnect is available then. The application can clear a disconnected call by dropping the call.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use this LINEDISCONNECTMODE_ value if it is not supported on the negotiated version (LINEDISCONNECTMODE_NORMAL or _UNKNOWN could be used instead).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLSTATE, LINECALLSTATUS, LINEDIALPARAMS


LINEERR_ Constants

This is the list of error codes that TAPI can return when invoking operations on lines, addresses, or calls. Consult the individual function descriptions to determine which of these error codes a particular function can return.

LINEERR_ADDRESSBLOCKED
The specified address is blocked from being dialed on the specified call.
LINEERR_ADDRESSBLOCKED
The target call address has call blocking enabled.
LINEERR_ALLOCATED
The line cannot be opened due to a persistent condition, such as that of a serial port being exclusively opened by another process.
LINEERR_BADDEVICEID
The specified device identifier or line device identifier (such as in a dwDeviceID parameter) is invalid or out of range.
LINEERR_BEARERMODEUNAVAIL
The bearer mode member in LINECALLPARAMS is invalid, the bearer mode specified in LINECALLPARAMS is not available, or the call's bearer mode cannot be changed to the specified bearer mode.
LINEERR_BILLINGREJECTED
The billing mode of the call was rejected.
LINEERR_CALLUNAVAIL
All call appearances on the specified address are currently in use.
LINEERR_COMPLETIONOVERRUN
The maximum number of outstanding call completions has been exceeded.
LINEERR_CONFERENCEFULL
The maximum number of parties for a conference has been reached, or the requested number of parties cannot be satisfied.
LINEERR_DIALBILLING
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALDIALTONE
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALPROMPT
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALQUIET
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALVOICEDETECT
Use of the ":" dial modifier is not supported. This value is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEERR_DISCONNECTED
The call has been disconnected. This value is exposed only to applications that negotiate a TAPI version of 2.2 or higher.
LINEERR_INCOMPATIBLEAPIVERSION
The application requested a TAPI version or version range that is either incompatible with, or cannot be supported by, the Telephony API implementation and the corresponding service provider.
LINEERR_INCOMPATIBLEEXTVERSION
The application requested an extension version range that is either invalid or cannot be supported by the corresponding service provider.
LINEERR_INIFILECORRUPT
The telephon.ini file cannot be read or understood properly by TAPI because of internal inconsistencies or formatting problems. For example, the [Locations], [Cards], or [Countries] section of the telephon.ini file may be corrupted or inconsistent.
LINEERR_INUSE
The line device is in use and cannot currently be configured, allow a party to be added, allow a call to be answered, allow a call to be placed, or allow a call to be transferred.
LINEERR_INVALADDRESS
A specified address is either invalid or not allowed. If invalid, the address contains invalid characters or digits, or the destination address contains dialing control characters (W, @, $, or ?) that are not supported by the service provider. If not allowed, the specified address is either not assigned to the specified line or is not valid for address redirection.
LINEERR_INVALADDRESSID
The specified address identifier is either invalid or out of range.
LINEERR_INVALADDRESSMODE
The specified address mode is invalid.
LINEERR_INVALADDRESSSTATE
The specified address state contains one or more bits that are not LINEADDRESSSTATE_ constants.
LINEERR_INVALADDRESSTYPE
The application referenced an address type that is not valid. This value is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINEERR_INVALAGENTACTIVITY
The specified agent activity is not valid.
LINEERR_INVALAGENTACTIVITY
The application invoking this operation is the target of the indirect handoff. That is, TAPI has determined that the calling application is also the highest priority application for the given media type. This value is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEERR_INVALAGENTGROUP
The specified agent group information is not valid or contains errors. The requested action has not been carried out.
LINEERR_INVALAGENTGROUP
The application referenced an agent group that is not valid. This value is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEERR_INVALAGENTID
The specified agent identifier is invalid.
LINEERR_INVALAGENTID
An invalid agent identifier was used. This value is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEERR_INVALAGENTSESSIONSTATE
The agent session state is invalid. This value is exposed only to applications that negotiate a TAPI version of 2.2 or higher.
LINEERR_INVALAGENTSKILL
The skill group entered is invalid.
LINEERR_INVALAGENTSTATE
The specified agent state is not valid or contains errors. No changes have been made to the agent state of the specified address.
LINEERR_INVALAGENTSTATE
The application referenced an agent state that is not valid. This value is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEERR_INVALAGENTSUPERVISOR
The agent supervisor indicator is invalid.
LINEERR_INVALAPPHANDLE
The application handle (such as specified by a hLineApp parameter) or the appliction registration handle is invalid.
LINEERR_INVALAPPNAME
The specified application name is invalid. If an application name is specified by the application, it is assumed that the string does not contain any non-displayable characters, and is zero-terminated.
LINEERR_INVALBEARERMODE
The specified bearer mode is invalid.
LINEERR_INVALCALLCOMPLMODE
The specified completion is invalid.
LINEERR_INVALCALLHANDLE
The specified call handle is not valid. For example, the handle is not NULL but does not belong to the given line. In some cases, the specified call device handle is invalid.
LINEERR_INVALCALLPARAMS
The specified call parameters are invalid.
LINEERR_INVALCALLPRIVILEGE
The specified call privilege parameter is invalid.
LINEERR_INVALCALLSELECT
The specified select parameter is invalid.
LINEERR_INVALCALLSTATE
The current state of a call is not in a valid state for the requested operation.
LINEERR_INVALCALLSTATELIST
The specified call state list is invalid.
LINEERR_INVALCARD
The permanent card identifier specified in dwCard could not be found in any entry in the [Cards] section in the registry.
LINEERR_INVALCOMPLETIONID
The completion identifier is invalid.
LINEERR_INVALCONFCALLHANDLE
The specified call handle for the conference call is invalid or is not a handle for a conference call.
LINEERR_INVALCONSULTCALLHANDLE
The specified consultation call handle is invalid.
LINEERR_INVALCOUNTRYCODE
The specified country code is invalid.
LINEERR_INVALDEVICECLASS
The line device has no associated device for the given device class, or the specified line does not support the indicated device class.
LINEERR_INVALDEVICEHANDLE
The line device handle is invalid.
LINEERR_INVALDIALPARAMS
The dialing parameters are invalid.
LINEERR_INVALDIGITLIST
The specified digit list is invalid.
LINEERR_INVALDIGITMODE
The specified digit mode is invalid.
LINEERR_INVALDIGITS
The specified termination digits are not valid.
LINEERR_INVALEXTVERSION
The service provider extension version number is invalid.
LINEERR_INVALFEATURE
The dwFeature parameter is invalid.
LINEERR_INVALFEATURE
The application invoked a feature that is not available on this line.
LINEERR_INVALGROUPID
The specified group identifier is invalid.
LINEERR_INVALLINEHANDLE
The specified call, device, line device, or line handle is invalid.
LINEERR_INVALLINESTATE
The device configuration may not be changed in the current line state. The line may be in use by another application or a dwLineStates parameter contains one or more bits that are not LINEDEVSTATE_ constants. The LINEERR_INVALLINESTATE value can also indicate that the device is DISCONNECTED or OUTOFSERVICE. These states are indicated by setting the bits corresponding to the LINEDEVSTATUSFLAGS_CONNECTED and LINEDEVSTATUSFLAGS_INSERVICE values to 0 in the dwDevStatusFlags member of the LINEDEVSTATUS structure returned by the lineGetLineDevStatus function.
LINEERR_INVALLOCATION
The permanent location identifier specified in dwLocation could not be found in any entry in the [Locations] section in the registry.
LINEERR_INVALMEDIALIST
The specified media list is invalid.
LINEERR_INVALMEDIAMODE
The list of media types (modes) to be monitored contains invalid information, the specified media type parameter is invalid, or the service provider does not support the specified media type. The media types supported on the line are listed in the dwMediaModes member in the LINEDEVCAPS structure.
LINEERR_INVALMESSAGEID
The number given in dwMessageID is outside the range specified by the dwNumCompletionMessages member in the LINEADDRESSCAPS structure.
LINEERR_INVALPARAM
A parameter or structure that a parameter points to contains invalid information, a country code is invalid, a window handle is invalid, or the specified forward list parameter contains invalid information.
LINEERR_INVALPARKID
The park identifier is invalid.
LINEERR_INVALPARKMODE
The specified park mode is invalid.
LINEERR_INVALPASSWORD
The specified password is not correct and the requested action has not been carried out.
LINEERR_INVALPASSWORD
The application used an invalid password. This value is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters (such as lpCallList, lpdwAPIVersion, lpExtensionID, lpdwExtVersion, lphIcon, lpLineDevCaps, and lpToneList) are invalid, or a required pointer to an output parameter is NULL.
LINEERR_INVALPRIVSELECT
An invalid flag or combination of flags was set for the dwPrivileges parameter.
LINEERR_INVALRATE
The specified rate is invalid.
LINEERR_INVALREQUESTMODE
The LINEREQUESTMODE indicator is invalid.
LINEERR_INVALTERMINALID
The specified terminal identifier is invalid.
LINEERR_INVALTERMINALMODE
The specified terminal modes parameter is invalid.
LINEERR_INVALTIMEOUT
Timeouts are not supported or a value falls outside the valid range specified in LINEDEVCAPS.
LINEERR_INVALTONE
The specified custom tone does not represent a valid tone or is made up of too many frequencies or the specified tone structure does not describe a valid tone.
LINEERR_INVALTONELIST
The specified tone list is invalid.
LINEERR_INVALTONEMODE
The specified tone mode parameter is invalid.
LINEERR_INVALTRANSFERMODE
The specified transfer mode parameter is invalid.
LINEERR_LINEMAPPERFAILED
LINEMAPPER was the value passed in the dwDeviceID parameter, but no lines were found that match the requirements specified in the lpCallParams parameter.
LINEERR_NOCONFERENCE
The specified call is not a conference call handle or a participant call.
LINEERR_NODEVICE
The specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized. Alternately, the line device has no associated device for the given device class.
LINEERR_NODRIVER
Either tapiaddr.dll could not be located or the telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. The user should be advised to use the Telephony Control Panel to correct the problem.
LINEERR_NOMEM
Insufficient memory to perform the operation, or unable to lock memory.
LINEERR_NOMULTIPLEINSTANCE
A telephony service provider that does not support multiple instances is listed more than once in the [Providers] section in the registry. The application should advise the user to use the Telephony Control Panel to remove the duplicated driver.
LINEERR_NOMULTIPLEINSTANCE
Multiple instances of this service provider are not allowed.
LINEERR_NOREQUEST
There currently is no request pending of the indicated mode, or the application is no longer the highest-priority application for the specified request mode.
LINEERR_NOTOWNER
The application does not have owner privilege to the specified call.
LINEERR_NOTREGISTERED
The application is not registered as a request recipient for the indicated request mode.
LINEERR_OPERATIONFAILED
The operation failed for an unspecified or unknown reason.
LINEERR_OPERATIONUNAVAIL
The operation is not available, such as for the given device or specified line.
LINEERR_RATEUNAVAIL
The service provider currently does not have enough bandwidth available for the specified rate.
LINEERR_REINIT
If TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then lineInitialize, lineInitializeEx, or lineOpen requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitialize or lineInitializeEx.
LINEERR_REINIT
The application attempted to initialize TAPI twice.
LINEERR_REQUESTOVERRUN
More requests are pending than the device can handle.
LINEERR_RESOURCEUNAVAIL
Insufficient resources to complete the operation. For example, a line cannot be opened due to a dynamic resource overcommitment.
LINEERR_STRUCTURETOOSMALL
The dwTotalSize member of a structure does not specify enough memory to contain the fixed portion of the specified structure.
LINEERR_TARGETNOTFOUND
A target for the call handoff was not found. This can occur if the named application did not open the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen. Or, in the case of media-mode handoff, no application has opened the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen and with the media type specified in the dwMediaMode parameter having been specified in the dwMediaModes parameter of lineOpen.
LINEERR_TARGETSELF
The application invoking this operation is the target of the indirect handoff. That is, TAPI has determined that the calling application is also the highest priority application for the given media type.
LINEERR_UNINITIALIZED
The operation was invoked before any application called lineInitialize or lineInitializeEx.
LINEERR_USERCANCELLED
The user cancelled the call. This value is exposed only to applications that negotiate a TAPI version of 2.2 or higher.
LINEERR_USERUSERINFOTOOBIG
The string containing user-user information exceeds the maximum number of bytes specified in the dwUUIAcceptSize, dwUUIAnswerSize, dwUUIDropSize, dwUUIMakeCallSize, or dwUUISendUserUserInfoSize member of LINEDEVCAPS, or the string containing user-user information is too long.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions. The values 0x80000000 through 0xBFFFFFFF are reserved, while 0x00000000 through 0x7FFFFFFF are used as request identifiers.

If an application gets an error return that it does not specifically handle (such as an error defined by a device-specific extension), it should treat the error as a LINEERR_OPERATIONFAILED (for an unspecified reason).

When invoking the LINEERR_constants which are new with TAPI 3.0, the tapierr.mc file must be updated with new messages.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEADDRESSCAPS, LINEDEVCAPS, LINEDEVSTATUS, lineGetLineDevStatus, lineInitialize, lineInitializeEx, lineOpen, lineShutdown


LINEFEATURE_ Constants

The LINEFEATURE_ constants list the operations that can be invoked on a line using this API.

LINEFEATURE_DEVSPECIFIC
Device-specific operations can be used on the line.
LINEFEATURE_DEVSPECIFICFEAT
Device-specific features can be used on the line.
LINEFEATURE_FORWARD
Forwarding of all addresses can be used on the line.
LINEFEATURE_FORWARDDND
The lineForward function (with an empty destination address) can be used to turn on the Do Not Disturb feature on all addresses on the line. LINEFEATURE_FORWARD will also be set. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEFEATURE_FORWARDFWD
The lineForward function can be used to forward calls on all address on the line to other numbers. LINEFEATURE_FORWARD will also be set. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEFEATURE_MAKECALL
An outgoing call can be placed on this line using an unspecified address.
LINEFEATURE_SETDEVSTATUS
The lineSetLineDevStatus function can be invoked on the line device. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEFEATURE_SETMEDIACONTROL
Media control can be set on this line.
LINEFEATURE_SETTERMINAL
Terminal modes for this line can be set.

Note If neither of the new modified "FORWARD" bits is set in the dwLineFeatures member in LINEDEVSTATUS but the LINEFEATURE_FORWARD bit is set, then any of the forward modes can work; the service provider has simply not specified which ones.

No extensibility. All 32 bits are reserved.

The LINEFEATURE_ constants are used in LINEDEVSTATUS (returned by lineGetLineDevStatus). LINEDEVSTATUS reports, for a given line, which line features can actually be invoked while the line is in the current state. An application would make this determination dynamically after line state changes, typically caused by address or call-related activities on the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEDEVSTATUS, lineForward, lineGetLineDevStatus, lineSetLineDevStatus


LINEFORWARDMODE_ Constants

The LINEFORWARDMODE_ bit-flag constants describe the conditions under which calls to an address can be forwarded.

LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYNA
Forward all calls on busy/no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward on busy/no answer all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_BUSYSPECIFIC
Forward on busy all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward on no answer all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_UNAVAIL
Calls are forwarded, but the conditions under which forwarding will occur are not known, and will never be known by the service provider. (TAPI versions 1.4 and later)
LINEFORWARDMODE_UNCOND
Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no answer conditions.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Unconditionally forward all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_UNKNOWN
Calls are forwarded, but the conditions under which forwarding will occur are not known at this time. It is possible that the conditions may become known at a future time. (TAPI versions 1.4 and later)

No extensibility. All 32 bits are reserved.

The bit flags defined by LINEFORWARDMODE_ are not orthogonal. Unconditional forwarding ignores any specific condition such as busy or no answer. If unconditional forwarding is not in effect, then forwarding on busy and on no answer can be controlled separately or not separately. If controlled separately, the LINEFORWARDMODE_BUSY and LINEFORWARDMODE_NOANSW flags can be used separately. If not controlled separately, the flag LINEFORWARDMODE_BUSYNA must be used. Similarly, if forwarding of internal and external calls can be controlled separately, then LINEFORWARDMODE_INTERNAL and LINEFORWARDMODE_EXTERNAL flags can be used separately; otherwise the combination is used.

Address capabilities indicate which forwarding modes are available for each address assigned to a line. An application can use lineForward to set forwarding conditions at the switch.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINEFORWARDMODE_ values if the negotiated version does not support them.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEGATHERTERM_ Constants

The LINEGATHERTERM_ bit-flag constants describe the conditions under which buffered digit gathering is terminated.

LINEGATHERTERM_BUFFERFULL
The requested number of digits has been gathered. The buffer is full.
LINEGATHERTERM_CANCEL
The request was canceled by this application, by another application, or because the call terminated.
LINEGATHERTERM_FIRSTTIMEOUT
The first digit timeout expired. The buffer contains no digits.
LINEGATHERTERM_INTERTIMEOUT
The inter-digit timeout expired. The buffer contains at least one digit.
LINEGATHERTERM_TERMDIGIT
One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEGENERATETERM_ Constants

The LINEGENERATETERM_ bit-flag constants describe the conditions under which digit or tone generation is terminated.

LINEGENERATETERM_CANCEL
The digit or tone generation request was canceled by this application, by another application, or because the call terminated. This value can also be returned when digit or tone generation cannot be completed due to internal failure of the service provider.
LINEGENERATETERM_DONE
The requested number of digits or requested tones have been generated for the requested duration.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINELOCATIONOPTION_ Constants

The LINELOCATIONOPTION_ constants define values used in the dwOptions member of the LINELOCATIONENTRY structure returned as part of the LINETRANSLATECAPS structure returned by lineGetTranslateCaps.

LINELOCATIONOPTION_PULSEDIAL
The default dialing mode at this location is pulse dialing. If this bit is set, lineTranslateAddress will insert a "P" dial modifier at the beginning of the dialable string returned when this location is selected. If this bit is not set, lineTranslateAddress will insert a "T" dial modifier at the beginning of the dialable string.

Not extensible. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEINITIALIZEEXOPTION_ Constants

The LINEINITIALIZEEXOPTION_ constants specify which event notification mechanism to use when initializing a session.

LINEINITIALIZEEXOPTION_CALLHUBTRACKING
The application desires to use the call hub tracking event notification mechanism. This constant is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINEINITIALIZEEXOPTION_USECOMPLETIONPORT
The application desires to use the Completion Port event notification mechanism. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEINITIALIZEEXOPTION_USEEVENT
The application desires to use the Event Handle event notification mechanism. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher.
LINEINITIALIZEEXOPTION_USEHIDDENWINDOW
The application desires to use the Hidden Window event notification mechanism. This flag is exposed only to applications that negotiate a TAPI version of 2.0 or higher.

See lineInitializeEx for further details on the operation of these options.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEMEDIACONTROL_ Constants

The LINEMEDIACONTROL_ bit-flag constants describe a set of generic operations on media streams. The interpretations are determined by the media stream. The line device must have the media-control capability for any media-control operation to be effective.

LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.

The speed of the media stream is returned to normal.

LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RESET
Reset the media stream. Equivalent to an end-of-input. All buffers are released.
LINEMEDIACONTROL_RESUME
Resume a paused media stream.
LINEMEDIACONTROL_START
Start the media stream.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Media control is provided to improve performance of actions on media streams in response to telephony-related events. The application should normally manage a media stream through the media-specific API. The media-control functionality provided here is not intended to replace the native media APIs.

Media-control actions can be associated with the detection of digits, the detection of tones, the transition into a call state, and the detection of a media type. Consult a line's device capabilities to determine whether media control is available on the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEMEDIAMODE_ Constants

The LINEMEDIAMODE_ constants describe media types (or modes)of a communications session or call.

LINEMEDIAMODE_AUTOMATEDVOICE
Voice energy was detected on the call, and the voice is locally handled by an automated application such as with an answering machine application. When a service provider cannot distinguish between interactive and automated voice on an incoming call, it will report the call as interactive voice.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call. Current modem protocols require the called station to initiate the handshake. For an incoming data modem call, the application can typically make no positive detection. How the service provider makes this determination is its choice. For example, a period of silence just after answering an incoming call can be used as a heuristic to decide that this might be a data modem call.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call. ADSI enhances voice calls with alphanumeric information downloaded to the phone and the use of soft buttons on the phone.
LINEMEDIAMODE_DIGITALDATA
A digital data stream of unspecified format.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_INTERACTIVEVOICE
Voice energy was detected on the call, and the call is handled as an interactive voice call with humans on both ends.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_VIDEO
The media type of the call is video. (TAPI versions 2.1 and later)
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_VOICEVIEW
The media type of the call is VoiceView. (TAPI versions 1.4 and later)
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not currently known and may become known later. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an incoming call's media type may be unknown until after the call has been answered and the media stream has been filtered to make a determination.

If the unknown media-mode flag is set, other media flags can also be set. This is used to signify that the media is unknown but that it is likely to be one of the other selected media types.

All 32 bits are reserved.

Note that bearer mode and media type are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media type of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax or data modem are media types that use a call with a 3.1 kHz voice bearer mode.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use this LINEMEDIAMODE_ value if not supported on the negotiated version.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEOFFERINGMODE_ Constants

The LINEOFFERINGMODE_ bit-flag constants (TAPI versions 1.4 and later) describe different substates of an offering call. A mode is available as call status to the application after the call state transitions to offering, and within the LINE_CALLSTATE message indicating the call is in LINECALLSTATE_OFFERING. These values are used when the call is on an address that is shared (bridged) with other stations (see LINEADDRESSSHARING_ Constants), primarily electronic key systems.

LINEOFFERINGMODE_ACTIVE
Indicates that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it can do so. If the call state mode is ZERO, the application should assume that the value is active (which would be the situation on a non-bridged address). (TAPI versions 1.4 and later)
LINEOFFERINGMODE_INACTIVE
Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light); software at the station set for automatic answering should preferably not answer the call, because this should be the prerogative at the primary (alerting) station, but lineAnswer may be used to connect the call. (TAPI versions 1.4 and later)

Not extensible. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINEOFFERINGMODE_ values if they are not supported on the negotiated version. Applications that are not cognizant of LINEOFFERINGMODE_ will most likely assume that a call that is in LINECALLSTATE_OFFERING is in LINEOFFERINGMODE_ACTIVE.

The LINEOFFERINGMODE_ACTIVE and LINEOFFERINGMODE_INACTIVE values are used when the call is on an address that is shared with other stations (bridged; see LINEADDRESSSHARING_ Constants), primarily electronic key systems. If the offering call state mode is "active," it means that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it can do so. If the call state mode is "inactive," the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light); software at the station set for automatic answering should preferably not answer the call, because this should be the prerogative at the primary (alerting) station, but lineAnswer can be used to connect the call. If the call state mode is ZERO, the application should assume that the value is active (which would be the situation on a non-bridged address).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEOPENOPTION_ Constants

The LINEOPENOPTION_ constants list the available options for opening a line.

LINEOPENOPTION_PROXY
The application is willing to handle requests from other applications that have the line open.
LINEOPENOPTION_SINGLEADDRESS
The application should be informed of new calls created on the line device only if those calls appear on the address specified in the dwAddressID member in the LINECALLPARAMS structure pointed to by the lpCallParams parameter.

See lineOpen for further details on the operation of these options.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEPARKMODE_ Constants

The LINEPARKMODE_ bit-flag constants describe different ways of parking calls.

LINEPARKMODE_DIRECTED
Specifies directed call park. The address where the call is to be parked must be supplied to the switch.
LINEPARKMODE_NONDIRECTED
Specifies nondirected call park. The address where the call is parked is selected by the switch and provided by the switch to the application.

No extensibility. All 32 bits are reserved.

The LINEPARKMODE_ constants are used when parking a call. Consult a line's address device capabilities to find out which park mode is available.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEREMOVEFROMCONF_ Constants

The LINEREMOVEFROMCONF_ scalar constants describe how parties participating in a conference call can be removed from a conference call.

LINEREMOVEFROMCONF_ANY
Any participating party can be removed from the conference call.
LINEREMOVEFROMCONF_LAST
Only the most recently added party can be removed from the conference call
LINEREMOVEFROMCONF_NONE
Parties cannot be removed from the conference call.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEREQUESTMODE_ Constants

The LINEREQUESTMODE_ bit-flag constants describe different types of telephony requests that can be made from one application to another.

LINEREQUESTMODE_DROP
A tapiRequestDrop request.
LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.
LINEREQUESTMODE_MEDIACALL
A tapiRequestMediaCall request.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINEROAMMODE_ Constants

The LINEROAMMODE_ bit-flag constants describe the roaming status of a line device.

LINEROAMMODE_HOME
The line is connected to the home network node.
LINEROAMMODE_ROAMA
The line is connected to the Roam-A carrier and calls are charged accordingly.
LINEROAMMODE_ROAMB
The line is connected to the Roam-B carrier and calls are charged accordingly.
LINEROAMMODE_UNAVAIL
The roam mode is unavailable and will not be known.
LINEROAMMODE_UNKNOWN
The roam mode is currently unknown but may become known later.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINESPECIALINFO_ Constants

The LINESPECIALINFO_ bit-flag constants describes special information signals that the network can use to report various reporting and network observation operations. They are special coded tone sequences transmitted at the beginning of network advisory recorded announcements.

LINESPECIALINFO_CUSTIRREG
This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category). LINESPECIALINFO_CUSTIRREG is also reported when billing information is rejected and when the dialed address is blocked at the switch.
LINESPECIALINFO_NOCIRCUIT
This special information tone precedes a no circuit or an emergency announcement (trunk blockage category).
LINESPECIALINFO_REORDER
This special information tone precedes a reorder announcement (equipment irregularity category). LINESPECIALINFO_REORDER is also reported when the telephone is kept offhook too long.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable and will not become known.
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but may become known later.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Special information tones are defined for advisory messages and are not normally used for billing or supervisory purpose.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETERMDEV_ Constants

The LINETERMDEV_ bit-flag constants describe different types of terminal devices.

LINETERMDEV_HEADSET
The terminal is a headset.
LINETERMDEV_PHONE
The terminal is a phone set.
LINETERMDEV_SPEAKER
The terminal is an external speaker and microphone.

No extensibility. All 32 bits are reserved.

These constants are used to characterize a line's terminal device and help an application to determine the nature of a terminal device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETERMMODE_ Constants

The LINETERMMODE_ bit-flag constants describe different types of events on a phone line that can be routed to a terminal device.

LINETERMMODE_BUTTONS
These are button-press events sent from the terminal to the line.
LINETERMMODE_DISPLAY
This is display information sent from the line to the terminal.
LINETERMMODE_HOOKSWITCH
These are hookswitch events sent from the terminal to the line.
LINETERMMODE_LAMPS
These are lamp events sent from the line to the terminal.
LINETERMMODE_MEDIABIDIRECT
This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.
LINETERMMODE_MEDIAFROMLINE
This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIATOLINE
This is the unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_RINGER
This is ringer-control information sent from the switch to the terminal.

No extensibility. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETERMSHARING_ Constants

The LINETERMSHARING_ bit-flag constants describe different ways in which a terminal can be shared between line devices, addresses, or calls.

LINETERMSHARING_PRIVATE
The terminal device is private to a single line device.
LINETERMSHARING_SHAREDCONF
The terminal device can be used by multiple lines. The lineSetTerminal requests of the various terminals end up being merged or conferenced at the terminal.
LINETERMSHARING_SHAREDEXCL
The terminal device can be used by multiple lines. The last line device to do a lineSetTerminal or TSPI_lineSetTerminal to the terminal for a given terminal mode will have exclusive connection to the terminal for that mode.

No extensibility. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETOLLLISTOPTION_ Constants

The LINETOLLLISTOPTION_ bit-flag constants describe options for manipulating a toll list.

LINETOLLLISTOPTION_ADD
A prefix is to be added to the toll list.
LINETOLLLISTOPTION_REMOVE
A prefix is to be removed from the toll list.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETONEMODE_ Constants

The LINETONEMODE_ constants describe different selections that are used when generating line tones.

LINETONEMODE_BEEP
The tone is a beep, such as that used to announce the beginning of a recording. Exact definition is service-provider defined.
LINETONEMODE_BILLING
The tone is a billing information tone such as a credit card prompt tone. Exact definition is service-provider defined.
LINETONEMODE_BUSY
The tone is a busy tone. Exact definition is service-provider defined.
LINETONEMODE_CUSTOM
The tone is a custom tone defined by its component frequencies, of type LINEGENERATETONE.
LINETONEMODE_RINGBACK
The tone is ringback tone. Exact definition is service-provider defined.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

These constants are used to define tones to be generated inband over a call to the remote party. Note that tone detection of non-custom tones does not use these constants.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETRANSFERMODE_ Constants

The LINETRANSFERMODE_ bit-flag constants describe different ways of resolving call transfer requests.

LINETRANSFERMODE_CONFERENCE
The transfer is resolved by establishing a three-way conference between the application, the party connected to the initial call, and the party connected to the consultation call. A conference call is created when this option is selected.
LINETRANSFERMODE_TRANSFER
The transfer is resolved by transferring the initial call to the consultation call. Both calls will become idle to the application.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETRANSLATEOPTION_ Constants

The LINETRANSLATEOPTION_ bit-flag constant describes an option used by address translation.

LINETRANSLATEOPTION_CANCELCALLWAITING
If a Cancel Call Waiting string is defined for the location, setting this bit will cause that string to be inserted at the beginning of the dialable string. This is commonly used by data modem and fax applications to prevent interruption of calls by call waiting beeps. If no Cancel Call Waiting string is defined for the location, this bit has no affect. Note that applications using this bit are advised to also set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags member of the LINECALLPARAMS structure passed in to lineMakeCall through the lpCallParams parameter, so that if the line device uses a mechanism other than dialable digits to suppress call interrupts that that mechanism will be invoked.
LINETRANSLATEOPTION_CARDOVERRIDE
The default calling card is to be overidden with a specified one.
LINETRANSLATEOPTION_FORCELD
This option forces the address (number) to be translated as long distance.
LINETRANSLATEOPTION_FORCELOCAL
This option forces the number (address) to be translated as local.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINECALLPARAMS, lineMakeCall, LINETRANSLATEOUTPUT


LINETRANSLATERESULT_ Constants

The LINETRANSLATERESULT_ bit-flag constants describe various results of an address translation.

LINETRANSLATERESULT_CANONICAL
Indicates that the input string was in valid canonical format.
LINETRANSLATERESULT_DIALBILLING
Indicates that the returned address contains a "$".
LINETRANSLATERESULT_DIALDIALTONE
Indicates that the returned address contains a "W".
LINETRANSLATERESULT_DIALPROMPT
Indicates that the returned address contains a "?".
LINETRANSLATERESULT_DIALQUIET
Indicates that the returned address contain a "@".
LINETRANSLATERESULT_INTERNATIONAL
Indicates that the call is being treated as an international call (country code specified in the destination address is different from the country code specified for the CurrentLocation).
LINETRANSLATERESULT_INTOLLLIST
Indicates that the local call is being dialed as long distance because the country/region has toll calling and the prefix appears in the TollPrefixList of the CurrentLocation.
LINETRANSLATERESULT_LOCAL
Indicates that the call is being treated as a local call (country code and area code specified in the destination address are the same as those specified for the CurrentLocation).
LINETRANSLATERESULT_LONGDISTANCE
Indicates that the call is being treated as a long distance call (country code specified in the destination address is the same but area code is different from those specified for the CurrentLocation).
LINETRANSLATERESULT_NOTINTOLLLIST
Indicates that the country/region supports toll calling but the prefix does not appear in the TollPrefixList, so the call is dialed as a local call. Note that if both INTOLLIST and NOTINTOLLIST are off, the current country/region does not support toll prefixes, and user-interface elements related to toll prefixes should not be presented to the user; if either such bit is on, the country/region does support toll lists, and the related user-interface elements should be enabled.
LINETRANSLATERESULT_NOTRANSLATION
Indicates that address translation is not available. This element is exposed only to applications that negotiate a TAPI version of 3.0 or higher.
LINETRANSLATERESULT_VOICEDETECT
Indicates that the returned dialable address contains a ":". This element is exposed only to applications that negotiate a TAPI version of 2.0 or higher.

Note The ":" (colon) character will be added to the list of characters that can be embedded in a dialable string and passed into destination addresses. Attempting to pass it from an application to a line device that supports an API version earlier than 2.0 will most likely result in LINEERR_INVALADDRESS, or possibly in the character being ignored entirely. The meaning of this character is "Pause until a voice prompt is detected, then continue dialing"; it is intended for use when automatically dialing into systems that give voice prompts, such as long distance calling card processors.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


LINETSPIOPTION_ Constants

LINETSPIOPTION_NONREENTRANT
TAPI should call functions in this service provider one at a time; it should wait from each function to return (but not for asynchronous functions to complete) before calling the same or another function, either on the same or a different thread, on the same or a different processor.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.


Phone Device Constants

This section contains an alphabetic listing of the following TAPI phone device constants:

  • PHONEBUTTONFUNCTION_ Constants
  • PHONEBUTTONMODE_ Constants
  • PHONEBUTTONSTATE_ Constants
  • PHONEERR_ Constants
  • PHONEFEATURE_ Constants
  • PHONEHOOKSWITCHDEV_ Constants
  • PHONEHOOKSWITCHMODE_ Constants
  • PHONEINITIALIZEEXOPTION_ Constants
  • PHONELAMPMODE_ Constants
  • PHONEPRIVILEGE_ Constants
  • PHONESTATE_ Constants
  • PHONESTATUSFLAGS_ Constants
  • STRINGFORMAT_ Constants


PHONEBUTTONFUNCTION_ Constants

The PHONEBUTTONFUNCTION_ scalar constants describe the functions commonly assigned to buttons on telephone sets.

PHONEBUTTONFUNCTION_ABBREVDIAL
The number to be dialed will be indicated using a short, abbreviated number consisting of one digit or a few digits.
PHONEBUTTONFUNCTION_BUSY
Makes the phone appear "busy" to incoming calls.
PHONEBUTTONFUNCTION_BRIDGEDAPP
Selects a particular appearance of a bridged address.
PHONEBUTTONFUNCTION_CALLAPP
Selects a particular call appearance.
PHONEBUTTONFUNCTION_CALLID
Requests display of caller ID on the phone's display.
PHONEBUTTONFUNCTION_CAMPON
Camps-on an extension that returns a busy indication. When the remote station returns to idle, the phone will be rung with a distinctive patterns. Picking up the local phone reinitiates the call.
PHONEBUTTONFUNCTION_COVER
Forwards all calls destined for this phone to another phone used for coverage.
PHONEBUTTONFUNCTION_CONFERENCE
Initiates a conference call or adds a call to a conference call.
PHONEBUTTONFUNCTION_CONNECT
Reconnects a call that is on consultation hold.
PHONEBUTTONFUNCTION_DATAOFF
Indicates that the next call is not a data call.
PHONEBUTTONFUNCTION_DATAON
Indicates that the next call is a data call.
PHONEBUTTONFUNCTION_DATETIME
Causes the phone to display current date and time; this information would be sent by the switch.
PHONEBUTTONFUNCTION_DIRECTORY
Calls up directory service from the switch.
PHONEBUTTONFUNCTION_DISCONNECT
Disconnects a call, such as after initiating a transfer.
PHONEBUTTONFUNCTION_DONOTDISTURB
Places the phone in "do not disturb" mode; incoming calls receive a busy signal or are forwarded to an operator or voice mail system.
PHONEBUTTONFUNCTION_DROP
Drops the active call.
PHONEBUTTONFUNCTION_FLASH
Generates the equivalent of an onhook/offhook sequence. A flash typically indicates that any digits typed next are to be understood as commands to the switch. On many switches, places an active call on consultation hold.
PHONEBUTTONFUNCTION_FORWARD
Initiates or changes call forwarding to this phone.
PHONEBUTTONFUNCTION_HOLD
Places the active call on hold.
PHONEBUTTONFUNCTION_INTERCOM
Connects to the intercom to broadcast a page.
PHONEBUTTONFUNCTION_LASTNUM
Redials last number dialed.
PHONEBUTTONFUNCTION_MSGINDICATOR
Controls the message indicator lamp.
PHONEBUTTONFUNCTION_MSGWAITOFF
Turns off a message waiting lamp.
PHONEBUTTONFUNCTION_MSGWAITON
Turns on a message waiting lamp.
PHONEBUTTONFUNCTION_MUTE
Mutes the phone's microphone device.
PHONEBUTTONFUNCTION_NIGHTSRV
Places the phone in the mode it is configured for during night hours.
PHONEBUTTONFUNCTION_NONE
A "dummy" function assignment that indicates that the button does not have a function.
PHONEBUTTONFUNCTION_PARK
Parks the active call on another phone, placing it on hold there.
PHONEBUTTONFUNCTION_PICKUP
Picks up a call ringing on another phone.
PHONEBUTTONFUNCTION_QUEUECALL
Queues a call to an outside number after it encounters a trunk-busy indication. When a trunk becomes later available, the phone will be rung with a distinctive pattern. Picking up the local phone reinitiates the call.
PHONEBUTTONFUNCTION_RECALL
Unholds a call.
PHONEBUTTONFUNCTION_REDIRECT
Redirects an incoming call to another extension before the call has been answered.
PHONEBUTTONFUNCTION_REJECT
Rejects an incoming call before the call has been answered.
PHONEBUTTONFUNCTION_REPDIAL
Repertory dialing—the number to be dialed is provided as a shorthand following pressing of this button.
PHONEBUTTONFUNCTION_RINGAGAIN
Initiates a request to be notified if a call cannot be completed normally because of a busy signal or no answer.
PHONEBUTTONFUNCTION_SAVEREPEAT
When pressed while a call or call attempt is active, it will remember that call's number or command. When pressed while no call is active (such as during dial tone), it repeats the most saved command.
PHONEBUTTONFUNCTION_SELECTRING
Allows the user to select the ring pattern of the phone.
PHONEBUTTONFUNCTION_SETREPDIAL
Programs the shorthand-to-phone number mappings accessible by means of repertory dialing (the "REPDIAL" button).
PHONEBUTTONFUNCTION_SENDCALLS
Sends all calls to another phone used for coverage; same as PHONEBUTTONFUNCTION_COVER.
PHONEBUTTONFUNCTION_SPEAKEROFF
Turns the phone's external speaker off.
PHONEBUTTONFUNCTION_SPEAKERON
Turns the phone's external speaker on.
PHONEBUTTONFUNCTION_STATIONSPEED
The number to be dialed is provided as a shorthand following pressing of this button. The mappings for station speed dialing are specific to this station (phone).
PHONEBUTTONFUNCTION_SYSTEMSPEED
The number to be dialed is provided as a shorthand following pressing of this button. The mappings for system speed dialing are configured inside the switch.
PHONEBUTTONFUNCTION_TRANSFER
Initiates a call transfer or completes the transfer of a call.
PHONEBUTTONFUNCTION_UNKNOWN
A "dummy" function assignment that indicates that the exact function of the button is unknown or has not been assigned.
PHONEBUTTONFUNCTION_VOLUMEDOWN
Decreases the volume of audio through the phone's handset speaker or speakerphone.
PHONEBUTTONFUNCTION_VOLUMEUP
Increases the volume of audio through the phone's handset speaker or speakerphone.

Values in the range 0x80000000 to 0xFFFFFFFF can be assigned for device-specific extensions; values in the range 0x00000000 to 0x7FFFFFFF are reserved.

The PHONEBUTTONFUNCTION_ constants have values commonly found on current telephone sets. These button functions can be used to invoke the corresponding function from the switch using lineDevSpecificFeature. Note that TAPI does not define the semantics of the button functions; it only provides access to the corresponding function. The behavior associated with each of the function values above is generic and can vary based on the telephony environment.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONEBUTTONMODE_ Constants

The PHONEBUTTONMODE_ bit-flag constants describe the button classes.

PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
PHONEBUTTONMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding button but has only a lamp.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, 0 through 9, '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.

No extensibility. All 32 bits are reserved.

This enumeration type is used in the PHONECAPS data structure to describe the meaning associated with the phone's buttons.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONEBUTTONSTATE_ Constants

The PHONEBUTTONSTATE_ bit-flag constants describe the button's positions.

PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).
PHONEBUTTONSTATE_UNAVAIL
Indicates that the up or down state of the button is not known to the service provider, and will not become known at a future time. (TAPI versions 1.4 and later)
PHONEBUTTONSTATE_UNKNOWN
Indicates that the up or down state of the button is not known at this time, but may become known at a future time. (TAPI versions 1.4 and later)
PHONEBUTTONSTATE_UP
The button is in the "up" state.

No extensibility. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the phone, and to not use those PHONEBUTTONSTATE_ values that the negotiated version does not support.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONEERR_ Constants

This is the list of error codes that the implementation can return when invoking operations on phone devices. Consult the individual function descriptions to determine which of these error codes each function can return.

PHONEERR_ALLOCATED
The specified resource is already allocated.
PHONEERR_BADDEVICEID
The specified device identifier is invalid or out of range.
PHONEERR_DISCONNECTED
The call was disconnected.
PHONEERR_INCOMPATIBLEAPIVERSION
The application requested an API version or version range that cannot be supported by the Telephony API implementation or the corresponding service provider.
PHONEERR_INCOMPATIBLEEXTVERSION
The application requested an extension version or version range that cannot be supported by the service provider.
PHONEERR_INIFILECORRUPT
Because of internal inconsistencies or formatting problems in the telephon.INI file, it cannot be read and understood properly by TAPI.
PHONEERR_INUSE
The device is currently in use. The device cannot be configured.
PHONEERR_INVALAPPHANDLE
The application's specified usage handle or registration handle is invalid.
PHONEERR_INVALAPPNAME
The specified application name is invalid. If an application name is specified by the application, it is assumed that the string does not contain any nondisplayable characters and is NULL-terminated.
PHONEERR_INVALBUTTONLAMPID
The specified button/lamp identifier is out of range or invalid.
PHONEERR_INVALBUTTONMODE
The button mode parameter is invalid.
PHONEERR_INVALBUTTONSTATE
The button states parameter is invalid.
PHONEERR_INVALDATAID
The specified data identifier is invalid.
PHONEERR_INVALDEVICECLASS
The specified phone does not support the indicated device class.
PHONEERR_INVALEXTVERSION
The service provider extension version number is invalid.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch device parameter is invalid.
PHONEERR_INVALHOOKSWITCHMODE
The hookswitch mode parameter is invalid.
PHONEERR_INVALLAMPMODE
The specified lamp mode parameter is invalid.
PHONEERR_INVALPARAM
A parameter, such as a row or column value or a window handle, is invalid or out of range.
PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
PHONEERR_INVALPRIVILEGE
The dwPrivilege parameter is invalid.
PHONEERR_INVALRINGMODE
The ring mode parameter is invalid.
PHONEERR_NODEVICE
The specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized or is corrupt in a way that was not detected at initialization.
PHONEERR_NODRIVER
The telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. The user should be advised to use the Telephony Control Panel to correct the problem.
PHONEERR_NOMEM
Insufficient memory to complete the requested operation, or unable to allocate or lock memory.
PHONEERR_NOTOWNER
The application does not have owner privilege to the specified phone device.
PHONEERR_OPERATIONFAILED
The operation failed for an unspecified reason.
PHONEERR_OPERATIONUNAVAIL
The operation is not available.
PHONEERR_REINIT
If TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then phoneInitialize, phoneInitializeEx or phoneOpen requests are rejected with this error until the last application shuts down its usage of the API (using phoneShutdown), at which time the new configuration becomes effective and applications are once again permitted to call phoneInitialize or phoneInitializeEx.
PHONEERR_REQUESTOVERRUN
The maximum number of outstanding phone requests has been exceeded.
PHONEERR_RESOURCEUNAVAIL
The operation cannot be completed because of resource overcommitment.
PHONEERR_STRUCTURETOOSMALL
The specified phone caps structure is too small.
PHONEERR_UNINITIALIZED
The operation was invoked before any application called phoneInitialize, phoneInitializeEx.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions; the values 0x80000000 through 0xBFFFFFFF are reserved; and 0x00000000 through 0x7FFFFFFF are used as request identifiers.

If an application gets an error return that it does not specifically handle (such as an error defined by a device-specific extension), it should treat the error as a PHONEERR_OPERATIONFAILED (for an unspecified reason).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

phoneInitialize, phoneInitializeEx, phoneOpen, phoneShutdown


PHONEFEATURE_ Constants

The PHONEFEATURE_ constants list the operations that can be invoked on a phone using this API. Each of the PHONEFEATURE_ values corresponds to a TAPI function with an identical or similar name.

PHONEFEATURE_GETBUTTONINFO
0x00000001
phoneGetButtonInfo
PHONEFEATURE_GETDATA
0x00000002
phoneGetData
PHONEFEATURE_GETDISPLAY
0x00000004
phoneGetDisplay
PHONEFEATURE_GETGAINHANDSET
0x00000008
phoneGetGain PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_GETGAINSPEAKER
0x00000010
phoneGetGain PHONEHOOKSWITCHDEV_SPEAKER
PHONEFEATURE_GETGAINHEADSET
0x00000020
phoneGetGain PHONEHOOKSWITCHDEV_HEADSET
PHONEFEATURE_GETHOOKSWITCHHANDSET
0x00000040
phoneGetHookSwitch PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_GETHOOKSWITCHSPEAKER
0x00000080
phoneGetHookSwitch PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_GETHOOKSWITCHHEADSET
0x00000100
phoneGetHookSwitch PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_GETLAMP
0x00000200
phoneGetLamp
PHONEFEATURE_GETRING
0x00000400
phoneGetRing
PHONEFEATURE_GETVOLUMEHANDSET
0x00000800
phoneGetVolume PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_GETVOLUMESPEAKER
0x00001000
phoneGetVolume PHONEHOOKSWITCHDEV_SPEAKER
PHONEFEATURE_GETVOLUMEHEADSET
0x00002000
phoneGetVolume PHONEHOOKSWITCHDEV_HEADSET
PHONEFEATURE_SETBUTTONINFO
0x00004000
phoneSetButtonInfo
PHONEFEATURE_SETDATA
0x00008000
phoneSetData
PHONEFEATURE_SETDISPLAY
0x00010000
phoneSetDisplay
PHONEFEATURE_SETGAINHANDSET
0x00020000
phoneSetGain PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_SETGAINSPEAKER
0x00040000
phoneSetGain PHONEHOOKSWITCHDEV_SPEAKER
PHONEFEATURE_SETGAINHEADSET
0x00080000
phoneSetGain PHONEHOOKSWITCHDEV_HEADSET
PHONEFEATURE_SETHOOKSWITCHHANDSET
0x00100000
phoneSetHookSwitch PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_SETHOOKSWITCHSPEAKER
0x00200000
phoneSetHookSwitch PHONEHOOKSWITCHDEV_SPEAKER
PHONEFEATURE_SETHOOKSWITCHHEADSET
0x00400000
phoneSetHookSwitch PHONEHOOKSWITCHDEV_HEADSET
PHONEFEATURE_SETLAMP
0x00800000
phoneSetLamp
PHONEFEATURE_SETRING
0x01000000
phoneSetRing
PHONEFEATURE_SETVOLUMEHANDSET
0x02000000
phoneSetVolume PHONEHOOKSWITCHDEV_HANDSET
PHONEFEATURE_SETVOLUMESPEAKER
0x04000000
phoneSetVolume PHONEHOOKSWITCHDEV_SPEAKER
PHONEFEATURE_SETVOLUMEHEADSET
0x08000000
phoneSetVolume PHONEHOOKSWITCHDEV_HEADSET

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONEHOOKSWITCHDEV_ Constants

The PHONEHOOKSWITCHDEV_ bit-flag constants describe various audio I/O devices each with its own hookswitch controllable from the computer.

PHONEHOOKSWITCHDEV_HANDSET
This is a standard ear- and mouthpiece phone.
PHONEHOOKSWITCHDEV_HEADSET
This is a headset connected to the phone set.
PHONEHOOKSWITCHDEV_SPEAKER
This is a built-in loudspeaker and microphone. This could also be an externally connected adjunct speaker to the telephone set.

No extensibility. All 32 bits are reserved.

These constants are used in the PHONECAPS data structure to indicate the hookswitch device capabilities of a phone device. The PHONESTATUS structure reports the state of the phone's hookswitch devices. The function phoneSetHookSwitch and phoneGetHookSwitch use it as a parameter to select the phone's I/O device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONEHOOKSWITCHMODE_ Constants

The PHONEHOOKSWITCHMODE_ bit-flag constants describe the microphone and speaker components of a hookswitch device.

PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_UNKNOWN
The device's hookswitch mode is currently unknown.

No extensibility. All 32 bits are reserved.

These constants are used to provide an individual level of control over the microphone and speaker components of a phone device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONEINITIALIZEEXOPTION_ Constants

The PHONEINITIALIZEEXOPTION_ constants specify which event notification mechanism to use when initializing a session.

PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT
The application desires to use the Completion Port event notification mechanism.
PHONEINITIALIZEEXOPTION_USEEVENT
The application desires to use the Event Handle event notification mechanism.
PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW
The application desires to use the Hidden Window event notification mechanism.

See phoneInitializeEx for further details on the operation of these options.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONELAMPMODE_ Constants

The PHONELAMPMODE_ bit-flag constants describe various ways in which a phone's lamp can be lit.

PHONELAMPMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding lamp.
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
Steady means the lamp is continuously lit.
PHONELAMPMODE_UNKNOWN
The lamp mode is currently unknown.
PHONELAMPMODE_WINK
Wink means normal rate on and off.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Where the exact on and off cadences can differ across phone sets from different vendors, mapping of actual lamp lighting patterns for most phones onto the values listed above should be straightforward.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONEPRIVILEGE_ Constants

The PHONEPRIVILEGE_ bit-flag constants describe the various ways in which a phone device can be opened.

PHONEPRIVILEGE_MONITOR
An application that opens a phone device with the monitor privilege is informed about events and state changes occurring on the phone. The application cannot invoke any operations on the phone device that would change its state, so only status operations can be invoked. Multiple applications can monitor a phone device at any given time.
PHONEPRIVILEGE_OWNER
An application that opens a phone device with the owner privilege is allowed to change the state of the lamps, ringer, display, hookswitch, and data blocks of the phone. Opening a phone device in owner mode also provides monitoring of the phone device. Only one application is allowed to be the owner of a phone device at any given time.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


PHONESTATE_ Constants

The PHONESTATE_ bit-flag constants describe various status items for a phone device.

PHONESTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shut down and reinitialize their connection to TAPI to obtain the updated information.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the PC is plugged in with TAPI active.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the PC is unplugged while TAPI is active.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device.
PHONESTATE_OTHER
Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.
PHONESTATE_OWNER
The number of owners for the phone device.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as for the appearance of new phone devices), the application should reinitialize its use of TAPI.
PHONESTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps


PHONESTATUSFLAGS_ Constants

The PHONESTATUSFLAGS_ bit-flag constants describe a variety of phone device status information.

PHONESTATUSFLAGS_CONNECTED
Specifies whether the phone is currently connected to TAPI. TRUE if connected, FALSE otherwise.
PHONESTATUSFLAGS_SUSPENDED
Specifies whether TAPI's manipulation of the phone device is suspended. TRUE if suspended, FALSE otherwise. An application's use of a phone device can be temporarily suspended when the switch wants to manipulate the phone in a way that cannot tolerate interference from the application.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


STRINGFORMAT_ Constants

The STRINGFORMAT_ constants describe different string formats.

STRINGFORMAT_ASCII
Specifies standard ASCII character format using one byte per character.
STRINGFORMAT_BINARY
This is an array of unsigned characters; could be used for numeric values.
STRINGFORMAT_DBCS
Specifies standard DBCS character format using one or two bytes per character.
STRINGFORMAT_UNICODE
Specifies standard Unicode character format using two bytes per character.

No extensibility. All 32 bits are reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


TAPIERR_ Constants

The TAPIERR_ constants provide information concerning function execution failures.

TAPIERR_CONNECTED
The operation can not be performed while the call state
TAPIERR_DESTBUSY
The call destination is busy.
TAPIERR_DESTNOANSWER
The call destination did not answer.
TAPIERR_DESTUNAVAIL
The call destination is not available.
TAPIERR_DEVICECLASSUNAVAIL
The device class needed is not available.
TAPIERR_DEVICEIDUNAVAIL
The device identifier needed is not available.
TAPIERR_DEVICEINUSE
The needed device is in use.
TAPIERR_DROPPED
The call was dropped.
TAPIERR_INVALDESTADDRESS
The pointer to the destination address is not valid, is NULL, or the destination address string is too long.
TAPIERR_INVALDEVICECLASS
The device class requested is not valid.
TAPIERR_INVALDEVICEID
The device class identifier requested is not valid.
TAPIERR_INVALPOINTER
The pointer does not reference a valid memory location. One or more of the pointers lpszDestAddress, lpszAppName, lpszCalledParty, or lpszComment have been specified but are invalid.
TAPIERR_INVALWINDOWHANDLE
The window handle is not valid.
TAPIERR_NOREQUESTRECIPIENT
No recipient application is available to handle the request. The user should start the recipient application and try again.
TAPIERR_NOTADMIN
The operation requested require admin priviledges.
TAPIERR_REQUESTCANCELLED
The assisted telephony request was cancelled.
TAPIERR_REQUESTFAILED
The request failed for unspecified reasons.
TAPIERR_REQUESTQUEUEFULL
A recipient application is active, but the request queue is full or there is insufficient memory to expand the queue. The application can try again later.
TAPIERR_UNKNOWNREQUESTID
The request identifier referenced is not valid.
TAPIERR_UNKNOWNWINHANDLE
An unknown window handle was referenced.

Any other TAPIERR_ values are nonfunctional in Win32-based applications and must not be used.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.


TAPI Device Classes

A device class is a group of related physical devices or device drivers through which applications send and receive the information or data that makes up a call. Every device class has a device class name that uniquely identifies the class, and provides information about the programming interface and commands that can be used to open and communicate with the devices in the class.

The Telephony Application Programming Interface (TAPI) associates devices from one or more device classes to each line or phone device. You access one of these devices by retrieving the device identifier for the device using the lineGetID or phoneGetID function. You supply the device class name, and the function returns the specific port name, device name, device handle, or device identifier that you need to open and access the device. The format of the information returned depends on the device class and is described in subsequent topics of this section.

Note The device identifier definitions apply to 16-bit and 32-bit TAPI. In some cases, the datatype of a media handle in the device identifier definition may be different from that specified by the Microsoft® Windows® operating system version 3.x or Microsoft® Win32® API. For example, Windows version 3.x and Win32 define wave device identifiers with the UINT type, but TAPI defines this device identifier with the DWORD type. In such cases, you should cast the media handle to the appropriate datatype when using it with the Windows version 3.x or Win32 API.

You also use device class names with the lineConfigDialog and phoneConfigDialog functions to enable the user to set configuration options for the given device, with the lineGetIcon and phoneGetIcon functions to retrieve an icon to represent the given device, and with the lineGetDevConfig and lineSetDevConfig functions to directly retrieve and set configuration options for the given device.

The following list shows device class names.

Device class name | Description
comm | Communications port.
comm/datamodem | Modem through a communications port.
comm/datamodem/portname | Name of the device to which a modem is connected.
wave/in | Wave audio device (input only).
wave/out | Wave audio device (output only).
wave/in/out | Wave audio device, full duplex.
midi/in | MIDI sequencer (input only).
midi/out | MIDI sequencer (output only).
tapi/line | Line device.
tapi/phone | Phone device.
ndis | Network device.
tapi/terminal | Terminal device.

Note These names are not case sensitive; you can use any combination of uppercase and lowercase letters.

Additional device classes and device class names may be available on a given system. In general, if a device does not belong to one of the default device classes, the manufacturer typically defines a new device class and assigns a unique device class name. Check the documentation for the device to determine what additional device classes are available for it. Note, however, that although the device class and media type are related, they are not the same. A media type describes call information format , and a device class defines the programming interface used to manage that information. So, even if a manufacturer defines a new media type, it is not necessarily true that the manufacturer also needs to define a new device class to support the mode.

The format of the configuration data used with the lineSetDevConfig and lineGetDevConfig functions also depends on the device class. In general, you use lineGetDevConfig to save a copy of the current device configuration data and then later use lineSetDevConfig with the saved configuration data to restore the device configuration to the previous state. This is a convenient way to temporarily change the configuration without requiring the user to manually restore it to the previous state. Because the exact format of the device configuration data may be different with each service provider, you should not use lineSetDevConfig and lineGetDevConfig to manipulate the device configuration data directly. Some formats are provided only for information.


comm

The comm device class consists of communications ports. You access these devices by using the Win32 file and communications functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_ASCII value and appending a null-terminated string that specifies the name of the communication device (such as the modem name).


comm/datamodem

The comm/datamodem device class consists of datamodem devices. You access these devices by using the Win32 file and communications functions. Devices in this class are associated with line devices that support the LINEMEDIAMODE_DATAMODEM media type, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID function fills a VARSTRING structure, setting dwStringFormat to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE hComm;            // Win32 file handle to data modem
CHAR   szDeviceName[1];  // name of data modem

The hComm member is the handle of the open communications port. This member is NULL if the port is not yet open or if the dwSelect parameter of lineGetID is not the LINECALLSELECT_CALL value. If a call is active, the service provider typically opens the port itself to get direct control of the communications hardware, but is only required to return a valid handle if the line is connected. The service provider opens the port using the FILE_FLAG_OVERLAPPED value and then configures the port using the settings specified by the lineSetDevConfig function. You can set additional configuration options for the device by using Win32 functions with the returned handle.

The szDeviceName member is a null-terminated string that specifies the name of the communications port associated with the line, address, or call.

If hComm is a valid handle, you can use it in subsequent calls to Win32 file functions, such as ReadFile and WriteFile, to send and receive data on the call. When you are finished using the communications port and preferably before you use the lineDeallocateCall function to deallocate the call, you must close the port by using the CloseHandle function.

When using the lineGetDevConfig and lineSetDevConfig functions, some service providers require that the configuration data for this device class have the following format:

typedef struct  tagDEVCFG  {
  DEVCFGHDR   dfgHdr;
  COMMCONFIG  commconfig;
} DEVCFG, *PDEVCFG, FAR* LPDEVCFG;

// Device setting information
typedef struct  tagDEVCFGDR  {
  DWORD       dwSize;
  DWORD       dwVersion;
  WORD        fwOptions;
  WORD        wWaitBong;
} DEVCFGHDR;

The following is device configuration information for use with the lineGetDevConfig and lineSetDevConfig functions.

dwSize
Sum of the size of the DEVCFGHDR structure and the actual size of the COMMCONFIG structure.
dwVersion
Version number of the Unimodem DevConfig structure. This member can be MDMCFG_VERSION (0x00010003).
fwOptions
Option flags that appear on the Unimodem Option page. This member can be a combination of these values:
TERMINAL_PRE (1)
Displays the pre-terminal screen.
TERMINAL_POST (2)
Displays the post-terminal screen.
MANUAL_DIAL (4)
Dials the phone manually, if capable of doing so.
LAUNCH_LIGHTS (8)
Displays the modem icon in the status area of the taskbar.

Only the LAUNCH_LIGHTS value is set by default

wWaitBong
Number of seconds (in two seconds granularity) to replace the wait for credit tone ($).
Commconfig
COMMCONFIG structure that can be used with the Win32 communications and modem configuration functions.


comm/datamodem/portname

The comm/datamodem/portname device class consists of the device names to which modems are attached. When this device name is specified in a call to the lineGetID function, the function fills the VARSTRING structure with a null-terminated ANSI (not Unicode) string specifying the name of the port to which the specified modem is attached, such as "COM1\0". This is intended primarily for identification purposes in the user interface, but could be used under some circumstances to open the device directly, bypassing the service provider (if the service provider does not already have the device open itself). If there is no port associated with the device, a null string ("\0") is returned in the VARSTRING structure (with a string length of 1).


wave/in

The wave/in device class consists of audio devices for low-level wave audio input. You access these devices by using the wave functions, which are described in the Microsoft Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media typem, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveInOpen function to open the device for input. You can use the resulting device handle to record digitized audio data from the line or phone device.

Although a "wave" device class also exists for low-level wave audio devices, you should always use the wave/in device class for low-level wave input.

For more information about the wave functions, see Multimedia Functions in the Platform SDK.


wave/out

The wave/out device class consists of audio devices for low-level wave audio output. You access these devices by using the wave functions, which are described in the Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media type, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveOutOpen function to open the device for output. You can use the resulting device handle to play digitized audio data at the line or phone device.

Although a "wave" device class also exists for low-level wave audio devices, you should always use the wave/out device class for low-level wave output.

For more information about the wave functions, see Multimedia Functions in the Platform SDK.


wave/in/out

The wave/in/out device class consists of full duplex audio devices. You access these devices by using the wave functions, which are described in the Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media type, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending two additional members:

DWORD DeviceInId;  // identifier of wave in audio device
DWORD DeviceOutId;  // identifier of wave out audio device

The DeviceInId and DeviceOutId members are identifiers of a closed audio device. You use these identifiers in a call to the waveOutOpen function to open the device for output. You can use the resulting device handle to play digitized audio data at the line or phone device.

For more information about the wave functions, see Multimedia Functions in the Platform SDK.


midi/in

The midi/in device class consists of MIDI sequencers that are used for input. You access these devices by using the MIDI functions, which are described in the Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiInOpen function to open the device for input. You can use the resulting device handle to record MIDI data from the line or phone device.

For more information about the MIDI functions, see Multimedia Functions in the Platform SDK.


midi/out

The midi/out device class consists of MIDI sequencers that are used for output. You access these devices by using the MIDI functions, which are described in the Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiOutOpen function to open the device for output. You can use the resulting device handle to play MIDI data at the line or phone device.

For more information about the MIDI functions, see Multimedia Functions in the Platform SDK.


tapi/line

The tapi/line device class consists of all line devices. You access these devices using the TAPI line functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member.

DWORD dwDeviceI;  // line device identifier

The dwDeviceId member is the identifier of the line device associated with the line handle given by lineGetID.

The phoneGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of line device identifiers

The adwDeviceIds member is an array containing the device identifiers of all line devices that are associated with the phone device. If there are no associated line devices, phoneGetID returns the PHONEERR_INVALDEVICECLASS value.


tapi/phone

The tapi/phone device class consists of all phone devices. You access these devices by using the TAPI phone functions.

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD dwDeviceI;  // phone device identifier

The dwDeviceId member is the identifier of the phone device associated with the phone handle given by phoneGetID.

The lineGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of phone device identifiers

The adwDeviceIds member is an array containing the device identifiers of all phone devices that are associated with the given line device. If there are no associated phone devices, lineGetID returns the LINEERR_INVALDEVICECLASS value.


ndis

The ndis device class consists of devices that can be associated with network driver interface specification (NDIS) media access control (MAC) drivers to support network communications. You access these devices by using functions.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE  hDevice;          // NDIS connection identifier
CHAR    szDeviceType[1];  // name of device

The hDevice member is the identifier to pass to a MAC, such as the asynchronous MAC for dial-up networking, to associate a network connection with the call/modem connection. The szDeviceType member is a null-terminated string specifying the name of the device associated with the identifier.


tapi/terminal

The tapi/terminal device class consists of the phone devices associated with each terminal on a line or the terminal on each line associated with a phone device. You access these devices by using the TAPI line device or phone device functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwDeviceId[];  // array of phone device identifiers

The adwDeviceId member is an array of phone device identifiers. There is one array element for each terminal specified by the dwNumTerminals member in the LINEDEVCAPS structure for the given line device. Each element specifies the identifier of the phone device associated with the corresponding terminal on the line. If there is no phone device associated with a terminal, the element is set to –1 (0xFFFFFFFF).

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwTerminalID[];  // array of terminal identifiers

The adwTerminalID member is an array of terminal identifiers. There is one array element for each line device identifier specified by the lineInitialize or lineInitializeEx function. Each array element contains the terminal identifier associated with the phone device for the given line device. If there is no phone device, the element is set to –1 (0xFFFFFFFF). The terminal identifiers range in value from zero to one less than the number specified by the dwNumTerminals member in the LINEDEVCAPS structure.


TAPI Version 3.0

TAPI Version 3.0 Start Page

Telephony Application Programming Interface

Version 3.0

Purpose

The Microsoft® Telephony Application Programming Interface (TAPI) version 3 is a Component Object Model (COM)-based API that merges classic and IP telephony.

Where Applicable

Possible applications include:

  • Multicast multimedia IP conferencing with quality of service (QOS)

  • Voice calls over the Internet using the H.323 protocol

  • Call center applications capable of tracking multiple agents

  • Basic voice calls on the Public Switched Telephone Network (PSTN)

  • PBX control

  • Interactive voice response (IVR) systems

  • Voice mail

Developer Audience

You can write TAPI-enabled applications in many languages, including Java, Visual Basic®, and C/C++. Familiarity with COM is required. For additional information on COM, please refer to the Component Services section of the Platform SDK. Previous development experience with telecommunications or other telephony applications is helpful but not necessary.

Run-time Requirements

TAPI version 3 enables development of communications applications for Microsoft Windows® 2000.

See Also

Microsoft Telephony Overview

TAPI 2.2 Overview

TAPI Service Provider Overview

Overview

General information about TAPI's architecture and components.

Reference

Documentation for the following:

  • Call and Media Control Reference

  • Call Center Controls

  • Rendezvous Reference

Feedback

Make error reports and feature requests directly to Microsoft.


TAPI Version 3 General Description

TAPI version 3 is a COM-based API that merges classic and IP telephony. Possible applications range from simple voice calls over the Public Switched Telephone Network (PSTN) to multicast multimedia IP conferencing with quality of service (QOS).

For additional information on TAPI 3 IP Telephony capabilities, please consult the "IP Telephony with TAPI 3" white paper, which can be found on the Microsoft web site.

There are four major components to TAPI 3:

  • TAPI 3 COM API
  • TAPI Server
  • Telephony Service Providers (TSPs)
  • Media Stream Providers (MSPs)

The following diagram illustrates current TAPI 3 architecture:

The TAPI 3 API is implemented as a suite of Component Object Model (COM) objects. Moving TAPI to the object-oriented COM model allows developers to write TAPI-enabled applications in many languages, such as Java, Visual Basic®, or C/C++. Use of COM enables component upgrades of TAPI features. For additional information on COM, please refer to the Component Services section of the Platform SDK.

The TAPI Server process (TAPISRV.EXE) abstracts the TAPI Service Provider Interface (TSPI) from TAPI 3 and TAPI 2.1, allowing TAPI 2.1 Telephony Service Providers to be used with TAPI 3, maintaining the internal state of TAPI. TAPISRV is implemented as a service process within SVCHOST.

Service Providers abstract provider-specific media transport mechanisms. They typically exist in pairs – a Telephony Service Provider (TSP) for call control and a Media Service Provider (MSP) for media control.

Telephony Service Providers (TSPs) are responsible for resolving the protocol-independent call model of TAPI into protocol-specific call control mechanisms. TAPI 3 provides backward compatibility with TAPI 2.1 TSPs. Two IP Telephony service providers (and their associated MSPs) ship by default with TAPI 3: the H.323 TSP and the IP Multicast Conferencing TSP.

Media Service Providers (MSPs) provide a uniform way to access the media streams in a call, supporting the DirectShowTM API as the primary media stream handler. TAPI MSPs implement DirectShow interfaces for a particular TSP and are required for any telephony service that makes use of DirectShow streaming. Generic streams are handled by the application.


TAPI 3 Requirements

TAPI version 3.0 requires Windows 2000.

TAPI version 3.1 requires Whistler.

IP Conferencing control using Rendezvous requires access to at least one ILS or NTDS server. If an NTDS server is in place, it can be used to locate an ILS server. If no NTDS server exists, the end user must know the name of the ILS server.


Call and Media Controls Overview

The following material provides a general review of the TAPI 3.0 call and media controls objects, interfaces, and methods for building end-user and server communications applications. About Call And Media Controls describes the main objects and contains a hyperlinked diagram showing both objects and interfaces. Using Call and Media Controls covers more specific information useful in writing applications, such as the .lib files required to compile and some code snippets.

For more information, see the Call and Media Control Reference.


About Call And Media Controls

TAPI 3.0 call and media controls are a generic set of COM objects, interfaces, and methods for making calls between two or more machines. In the context of TAPI 3.0, call refers not just to voice transmission over the public switched telephone network (PSTN) but to any medium and transport mechanism for which service providers exist: for example, a multimedia multicast conference running on a corporate intranet.

The five main objects in the TAPI 3.0 call and media control architecture are TAPI, Address, Terminal, Call, and CallHub. In addition, provision has been made for provider-specific interfaces. The diagram in About Call And Media Controls shows these objects with their associated interfaces and is hyperlinked to the object overviews and the interface reference section.

The following diagram illustrates how these objects interact, and it is hyperlinked into the relevant overview sections and reference pages.

Features

  • Abstracts both call and media functionality to allow different and seemingly incompatible communication protocols to expose a common interface to applications.
  • Based on the Component Object Model (COM) so applications can be written in nearly any language. If you require additional information on COM, please consult the Platform SDK.
  • Call control provided by Telephony Service Providers (TSPs), which implement transport-specific mechanisms.
  • Media control provided by Media Service providers (MSPs). Current MSPs use DirectShow™. DirectShow is a modular system of pluggable components called filters, arranged in a configuration called a filter graph. The filter graph manager oversees the connection of these filters and controls the stream's data flow. If you require additional information on DirectShow, please consult the Platform SDK.


TAPI Object

The TAPI object represents all telephony resources to which the local computer has access, allowing an application to enumerate all local and remote addresses. A TAPI 3.0 application must create an instance of the TAPI object and then initialize it.

The Initialize TAPI code snippet shows an example of TAPI object creation.

See TAPI Object Interfaces for a list of all interfaces associated with the TAPI object.


Address Object

The Address object represents an entity that can make or receive calls. This object exposes interfaces and methods that allow an application to perform a number of operations, such as:

  • Discover whether a specified address can support a particular set of media type needs.
  • Enumerate calls currently associated with the address.
  • Create or forward calls.
  • Get the name of the associated service provider.
  • If a media service provider exists, get interface pointers that allow detailed terminal manipulation.
  • Get and set other information, such as whether a message is waiting.

Most addresses are associated with a terminal, but this is not uniformly the case. For example, a remote TSP that provides access to equipment on a server will have an address on the local machine but not a terminal. A speakerless modem also has no terminal associated with its address.

If an address does not have an associated terminal, the ITTerminalSupport interface is not exposed on the object.

The Select an Address code snippet shows the basic process for acquiring an address object pointer.

See Address Object Interfaces for a list of all interfaces associated with the Address object.


Terminal Object

In TAPI version 3.0 and above, the TAPI object model uses terminal objects to represent the source or sink of a media stream associated with a call or communications session. This object model allows an application to specify at a detailed level how media are processed on a call. This model also allows multiple terminals to be selected at the same time, so, for example, a call can be played out of a speaker and recorded at the same time.

The Terminal object represents a source or renderer, such as a microphone or a speaker. An application chooses among available terminals based on the media direction and type or types involved in a communications session. Each associated media stream is then selected onto the appropriate terminal in order to start streaming.

Terminals are normally implemented by a media service provider and terminal objects will not be available if there is no MSP associated with a communications session. One exception to this exists: Starting with Windows 2000 SP1, an application can implement a form of pluggable terminal. This allows a conferencing server to create bridging terminals so that non-Windows 2000 SP1 or non-multicast H323 clients can be added to TAPI 3.0 multi-party SDP/IP multicast conferences.

Each terminal belongs to a terminal class. A terminal class represents a set of source or render capabilities. For example, a terminal that maps to a set of speakers would be identified as CLSID_SpeakersTerminal, and the service provider would be expected to implement volume control. TAPI 3.0 defines a set of terminal classes, an MSP can define additional classes, and an application can register new terminal classes. Each terminal class is assigned a globally unique identifier (GUID).

From the point of view of an application, a terminal is described by its terminal type and direction. The type may be either static or dynamic. A static terminal maps to hardware, such as a telephone or microphone. A dynamic terminal maps to a transient object, such as a file or a video window. Direction simply describes whether a given terminal is a source or a renderer.

The capabilities of a given terminal object can vary considerably depending on the current service provider pair in use. The MSP for a specialized device might implement an interface with methods appropriate to that device. That interface could be aggregated onto the terminal object and the methods made available to an application. Reference material on such methods will be found in the documentation for the MSP.

For terminal interfaces and methods implemented by TAPI 3.0, see Terminal Object Interfaces.

If the authors of a media service provider use the MSP Base Classes, they may choose to implement some of the Media Streaming Terminal's capabilities.

The Make a Call and Receive a Call code snippets show some examples of using a Terminal object.

Whistler: For information about how the terminal object has been expanded in Whistler, see the following topics:

  • File terminals
  • Multitrack terminals
  • Pluggable terminals

For code examples, see Using File Terminals, Using Multitrack Terminals and the Default Selection Mechanism, and Pluggable Terminal Registration.


File Terminals

[This is preliminary documentation and subject to change.]

In TAPI 3.1, the terminal object has been expanded to include a file terminal. File terminals provide a simple means to perform two commonly desired operations: the recording of a media stream or streams to a file, and subsequent playback of the recorded media to a stream.

Five basic objects are used to manipulate file terminals:

  • File Playback Terminal
  • File Recording Terminal
  • File Playback Track
  • File Recording Track
  • File Event

The File Terminal objects can be thought of as an abstraction for the storage, which is usually a file. Tracks correspond to the individual media data streams in that storage, such as when both voice and images are recorded.

For more information about file terminals, see the following topics:

  • File Playback Terminal and File Recording Terminal
  • Track Terminals

For code samples and task lists related to file terminals, see Using File Terminals.


File Playback Terminal and File Recording Terminal

[This is preliminary documentation and subject to change.]

The File Playback Terminal and File Recording Terminal expose the ITTerminal and ITMultiTrackTerminal interfaces. These objects also expose the ITMediaControl interface, which provides methods for stopping, starting, and media navigation.

The File Playback Terminal exposes the ITMediaPlayback interface, which has playback-specific methods.

The File Recording Terminal exposes the ITMediaRecord interface, which provides recording-specific methods.

As multitrack terminals, File Recording Terminal and File Playback Terminal each manage a collection of track terminals.


Track Terminals

[This is preliminary documentation and subject to change.]

Two types of track terminals are defined: Recording Track Terminal and Playback Track Terminal, which, respectively, belong to and are managed by File Recording Terminal and File Playback Terminal.

All track terminals expose the ITFileTrack and ITTerminal interfaces. The ITTerminal interface allows the selection of track terminals onto streams or calls.

Note Track terminals also expose a private interface, ITMediaControl, which the MSP uses. Applications should not attempt to access this interface.


Multitrack Terminals

[This is preliminary documentation and subject to change.]

TAPI 3.1 introduces the notion of a multitrack terminal, a terminal that, in essence, is a collection of "track" terminals. Multitrack terminals ease the programmer's load in situations where multiple media streams are involved in a communications session.

The File Recording Terminal is an example of a multitrack terminal. It consists of "tracks," where each "track" is a terminal corresponding to a stream in the recorded file.

A track terminal can be another multitrack terminal or a single-track terminal. A single-track terminal is a terminal that does not have any track terminals. A single-track terminal is a terminal in the TAPI 3.0 sense of the word.

For more information about multitrack terminals, see the following topics:

  • About Multitrack Terminals
  • Default Terminal Selection Mechanism
  • Manual Terminal Selection
  • Using Multitrack Terminals and the Default Selection Mechanism


About Multitrack Terminals

[This is preliminary documentation and subject to change.]

A multitrack terminal can be thought of as a terminal that is a collection of other terminals. Each child terminal (a "track") can be a multitrack terminal or a single-track terminal.

All multitrack terminals expose the ITMultiTrackTerminal interface, which includes generic methods for enumerating, creating, and removing track terminals from a multitrack terminal. All terminals, single-track and multitrack, expose the ITTerminal interface.

A client that has a pointer to an ITTerminal interface can discover whether the terminal is multitrack or single-track by querying the terminal for the ITMultiTrackTerminal interface, which is exposed only on multitrack terminals.

The parent terminal may use the ITTerminal interface of its track terminals, or it may require track terminals to expose private interfaces.

For more information, see Track Terminals.


Default Terminal Selection Mechanism

[This is preliminary documentation and subject to change.]

The concept of multitrack terminal makes it even more desirable for TAPI to provide a simplified method of selecting a terminal on a stream or streams. The Default Terminal Selection mechanism is designed to address this.

Selecting a Terminal on a Call

The Default Terminal Selection feature is provided via the ability to select a terminal on a call.

The call object exposes a new interface, ITBasicCallControl2. The interface exposes the same methods as ITBasicCallControl, plus three new methods: RequestTerminal, SelectTerminalOnCall, and UnselectTerminalOnCall.

ITBasicCallControl2::RequestTerminal creates a terminal, given the terminal class, direction, and media type. It looks through the lists of supported static and dynamic terminals to find and create the requested terminal.

ITBasicCallControl2::SelectTerminalOnCall selects the terminal (or, in the case of a multitrack terminal, enumerates, creates if needed, and selects the track terminals) on the stream (or streams) available on the call.

The algorithm for matching call streams to the terminal (or tracks available on the terminal) is described in the documentation for ITBasicCallControl2::SelectTerminalOnCall.

Calling ITBasicCallControl2::UnselectTerminalOnCall causes the terminal (single-track or multitrack) to be unselected from the call. See the method's documentation for more details.

Selecting a Terminal on ITStream

Selecting a single-track terminal on ITStream (by calling ITStream::SelectTerminal) selects the terminal on the stream. This is the usual TAPI 3.0 terminal selection procedure.

Only single-tracks terminals can be selected on a stream. Selecting a multitrack terminal on a stream will fail, because the stream will not recognize the media type and direction.


Manual Terminal Selection

[This is preliminary documentation and subject to change.]

If the rules of Default selection do not meet the needs of the application, the application has the option of selecting the terminal as it always has: that is, it can use ITStream to enumerate the streams present on the call and select the terminal on the appropriate streams (or, in case of multitrack terminals, create tracks for the streams and select created tracks on the streams).


Pluggable Terminals

[This is preliminary documentation and subject to change.]

Pluggable terminals allow an application to create terminals during run time. Terminals are normally created and controlled by a telephony service provider/media service provider (TSP/MSP) pair, and this remains the most versatile and stable means of manipulating terminals. However, some applications need to use simple terminals in situations where an appropriate TSP/MSP pair is not available. Only application writers who are thoroughly familiar with TSP/MSP operations should use pluggable terminals.

In TAPI version 3.1, pluggable terminals are added to the TAPI model. Pluggable terminals allow a third party to add a new terminal object that any MSP can use.

See Pluggable Terminal Registration and Writing a Pluggable Terminal for more information.


Call Object

The Call object represents an address's connection between the local address and one or more other addresses. All call control is done through the Call object. ITBasicCallControl and ITCallInfo are the most frequently used interfaces on the call object. These interfaces implement a variety of operations and queries, such as acquiring interface pointers for media streams or getting the caller ID. See the main overview sections on Session Operations and Session Information for reviews of those supported by TAPI.

A media service provider can implement provider-specific interfaces, which are aggregated on a call object by TAPI. For detailed information on what a provider has implemented, see the service provider's documentation.

The Make a Call and Receive a Call code snippets show some examples of using a Call object.

See Call Object Interfaces for a list of all interfaces associated with the Call object.


Phone Control and the Phone Object

[This is preliminary documentation and subject to change.]

TAPI 3.1 introduces COM-based phone controls. Familiarity with COM, OLE Automation, and scripting is assumed, as is knowledge of TAPI 3.0's object model and design. Knowledge of TAPI 2's phone control functions is useful in understanding this material.

Phone control is implemented in three levels of features, each of which builds upon the previous one:

  • Phone object. The first level defines how TAPI 2.x's phone devices (APIs, constants, and messages beginning with "phone") are exposed in the TAPI 3.1 object model. This involves a new phone object exposed from TAPI 3.1, with ITPhone as the default interface on the new object. The ITPhone interface, along with its associated constants, enumerated types, and events, generally exposes the same level of detail and functionality as the TAPI 2.x functions, constants, structures, and messages that begin with the word "phone." This level also involves new interfaces on several existing TAPI 3.x objects to facilitate creation of phone objects and association of phone objects with other objects to which they are related.
  • Automated phone control and call handling. The second level consists of an additional interface called ITAutomatedPhoneControl and its associated constants, enumerated types, and events. This is a secondary interface on the phone object. If the phone device was opened with owner privilege, you can use the QueryInterface method on the ITPhone interface to obtain an ITAutomatedPhoneControl interface pointer.
  • Windows 2000 Phone Dialer. The third level consists of changes to the Windows 2000 Phone Dialer application to implement specific user interactions.

Microsoft® or third parties can use the TAPI 3.1 object model to implement more advanced applications or services involving phones, including a service that allows universal serial bus (USB) handsets, for example, to be used for phone calls even if no user is logged in and no other TAPI application has been explicitly started.

In TAPI 3.0, a Phone MSP attempted to do something intelligent for phone devices that were associated with lines that were used on TAPI 3.0 calls. This was meant to support modems with software-switchable speakerphones built in. TAPI 3.1 applications that use this type of modem should use TAPI 3.1's phone objects to manipulate the modem's hookswitch state themselves.

See Phone Object Interfaces for a list of all interfaces associated with the Phone object. The phone control interfaces expose methods that allow detailed control over phone sets using COM.


CallHub Object

The CallHub object represents a third-party view of a multiparty call. The associated interfaces and methods get and set information concerning the hub, such as whether it is active. Using the CallHub object, a user with the required security can discover and potentially control other participants in a call.

A CallHub object cannot be created directly by an application. A CallHub object is created indirectly when an incoming call is received through TAPI 3.0.

TAPI 3.0 relies on TAPI service providers to provide the necessary information about calls to implement using the CallHub object. Since not all service providers provide this information, and not all hardware supports call hub tracking, the information available about the other users in the connection may be limited or nonexistent.

The Create a Simple Conference code snippet illustrates use of a CallHub object.

See CallHub Object Interfaces for a list of all interfaces associated with the CallHub object.


Stream Objects

Stream objects are an abstraction of the media stream or streams associated with a call session. The interfaces and methods exposed on stream and substream objects allow an application to exercise very detailed controls such as pausing a stream, adding new media types to a communications session, or adjusting the audio volume of a particular conference participant.

The two main types of stream are the stream and the substream. The interfaces and methods of a standard implementation are similar for both, but substreaming allowing a lower level of control. All media service providers (MSPs) must implement the basic stream control interfaces, but support for substreams is optional.

In addition, some service providers implement provider-specific interfaces for streams. For example, the IPConf MSP provides participant level controls. See IPConf MSP Interfaces for a summary. For other interfaces that might be implemented, see the service provider's documentation.

The MSP and TAPI create stream objects for a call during initial setup of an outgoing or incoming session. The application is responsible for identifying appropriate terminals for these streams, and selecting the terminals onto the streams.

Please note that in some cases an MSP may require that the application stop or pause streams prior to certain call session operations.

The stream interfaces are documented in the Media Service Provider Interface (MSPI) Reference.

The Select a Terminal code snippet shows an example of enumerating streams and selecting terminals onto them.


Events

Events are a crucial part of call handling under TAPI 3.0. Event handling includes four stages.

To register for and enable the reception of events

  1. Implement the ITTAPIEventNotification::Event method. (TAPI calls this method when an event occurs.) Typically, this implementation does no more than AddRef the IDispatch interface pointer, then post to the application's message pump.
  2. Register the ITTAPIEventNotification outgoing interface using the COM standard IConnectionPointContainer and IConnectionPoint interfaces, and pass the IConnectionPoint::Advise method a pointer to ITTAPIEventNotification::Event.
  3. Call the ITTAPI::put_EventFilter method to tell TAPI which events the application will handle. The event filter consists of ORed members of the TAPI_EVENT enumeration.

    Note You must call the ITTAPI::put_EventFilter method to set the event filter mask and enable reception of events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events.

You must also call the ITTAPI::RegisterCallNotifications method for each address object on which the application will handle calls.

See Event Interfaces for a list of all event interfaces. See Register Events for code snippets illustrating the registration process and Receive a Call for a code snippet showing one use of events.


Request Object

The Request Object is created using COM CoCreateInstance and exposes one interface, ITRequest. This interface exposes the MakeCall method, which allows a TAPI 3.0 application to use Assisted Telephony. Assisted Telephony provides telephony-enabled applications with a simple mechanism for making phone calls without requiring the developer to become fully literate in telephony.

For example, a spreadsheet application can add a "Make Call" button using Assisted Telephony without implementing the more elaborate controls available in a full TAPI application.

See the Assisted Telephony Overview for additional information.


Dispatch Mapper

The Dispatch Mapper is created using COM CoCreateInstance and exposes one interface, ITDispatchMapper. This interface allows an application to retrieve the dispatch pointer of another interface on an object, given the dispatch pointer of one interface and the GUID of another. This interface is provided to assist programmers using scripting applications which do not provide a means of readily polling the interfaces on an object.

The Dispatch Mapper uses an object's IObjectSafety interface to make sure the object is safe for scripting on the requested interface. If the object does not implement IObjectSafety, or if the object is not safe on this particular interface, the call will fail.


Provider-Specific Interfaces

TAPI 3.0 supports integration of service provider-specific interfaces into the standard objects, allowing applications to take advantage of provider-specific functionality. Additionally, TAPI 3.0 allows service providers to deliver vendor-specific events to applications as COM objects over the same interface on which the application receives standard events.

TAPI achieves this integration by aggregating provider-specific objects with the standard objects – TAPI, Address, Terminal, Call, and CallHub – and dispatching or delegating unknown methods to these provider-specific objects.

For example, a service provider may allow applications to obtain information about a call beyond what is exposed by the ITCallInfo interface. The vendor must define an interface that allows applications to make these extra queries and implement that interface on an object. This object also implements a vendor information-querying interface so that an application can discover what sorts of provider-specific functions might be available.

When the application obtains a reference to a call object, the application can use the new provider-specific interface and its methods as if they were implemented by the call object itself.

See Media Service Provider Interface (MSPI) Reference for a list of all standard MSP interfaces.

See IPConf MSP Interfaces for a list of all interfaces specific to the IPConf MSP.


Using Call And Media Controls

The following material provides assistance in using TAPI 3.0 call controls:

  • Using File Terminals
  • Using Multitrack Terminals and the Default Selection Mechanism
  • Pluggable Terminal Registration

For a diagram of all objects and interfaces, see About Call And Media Controls. For reference lists by functional area, see Call and Media Control Quick Reference.

Developers interested in writing IP multicast conferencing applications should consult About Rendezvous IP Telephony Conferencing.

Developers interested in writing Web IVR applications should examine Microsoft's Web Telephony Engine. Web Telephony is a platform for developing and running Web-based interactive voice response applications, ranging from simple IVR applications to complex, dual-access Internet applications that allow users to access a Web site by telephone as well as by computer. A Web Telephony application can be developed with any standard Web authoring technologies, including dynamic HTML,scripting languages, ActiveX controls, database access objects, and Active Server Pages.

Libraries required

A list of LIB files needed to compile various TAPI 3.0 applications, as of 3/1/99.

Hints and Tips

Some pitfalls to avoid.

Code Samples

In the Code Samples section of the Platform SDK under NetDS are example TAPI programs in C++, Visual Basic, and Java. You can locate them by searching on "INCOMING Sample Application" or "OUTGOING Sample Application".

Code Snippets

The code snippets briefly illustrate some basic operations, such as initializing TAPI and making a simple call.


Libraries Required

A list of .lib files required to compile various TAPI 3.0 applications, as of 1/22/01:

  • Advapi32.lib
  • Amstrmid.lib (ActiveMovie™ GUIDs)
  • Kernel32.lib
  • Mdhcpid.lib (multicast GUIDs)
  • Ole32.lib (COM)
  • Oleaut32.lib (COM Automation)
  • Rendid.lib (Rendezvous GUIDs)
  • Rpcndr.lib
  • Rpcns4.lib
  • Rpcrt4.lib
  • Sdpblbid.lib (Session Descriptor Protocol (SDP) GUIDs)
  • Strmiids.lib
  • User32.lib
  • Uuid.lib
  • Wldap32.lib
  • Ws2_32.lib

If you are using Microsoft Visual Studio®, you may need to update your version. In particular, Link.exe must carry a date of 3/19/98 or later.

Compiler defines must include _WIN32_WINNT set to at least 0x500 and _WIN32_DCOM.


Hints and Tips

The following are points to consider when writing a TAPI 3.0 application.

  1. COM CoInitialize indirectly creates windows (especially important for apartment threading). If a thread creates any windows, it must process messages. So, if your threads call CoInitialize, you need to run a message pump to prevent problems from occurring. For example, COM might stop marshaling properly, or methods on COM interfaces such as IGlobalInterfaceTable might hang.

    In apartment threading you must have a message pump regardless of whether you wait for synchronization objects. This is particularly important if you have a console application or you write a COM local/remote server object that is apartment threaded (where you don't have a console or a GUI, but the control just "runs" in the system).

    Use caution when calling the wait and synchronization functions, such as Sleep(), WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx, and so on. Instead, use MsgWaitForMultipleObjects and process the messages, or use CoWaitForMultipleHandles(), which will automatically detect what type of apartment the thread is in (STA or MTA) and will wait either in COM's modal loop (if STA) or block on WaitForMultipleObjects (if MTA). MsgWaitForMultipleObjects and CoWaitForMultipleHandles() also process windows messages according to the COM rules.

    For example, instead of:

      Sleep (5000);

    Use:

       {
   DWORD dwSignalled;
   HANDLE heventDone = CreateEvent(0, FALSE, FALSE, 0);

   CoWaitForMultipleHandles (COWAIT_ALERTABLE,
                         5000,
                         1,
                         &heventDone,
                         &dwSignalled);

   CloseHandle(heventDone);
   }
  2. ITTAPIEventNotification::Event is the apps Event routine that is called on TAPI3's callback thread. Look at Michelle Quinton's article in the November 1998 issue of Microsoft Journal for a good example of this. It uses the AddRef method to increase the reference count and does the actual processing on a separate thread. The more processing you do in the Event routine, the longer you block the TAPI callback thread and prevent other events from being sent.

    Do the minimum in the Event routine; instead, use one of your own threads where possible.

    HRESULT
STDMETHODCALLTYPE
CTAPIEventNotification::Event(
                              TAPI_EVENT TapiEvent,
                              IDispatch * pEvent
                             )
{
    //
    // addref the event so it doesn't go away
    //
    pEvent->AddRef();

    //
    // post a message to ourself
    //
    PostMessage(
                ghDlg,
                WM_PRIVATETAPIEVENT,
                (WPARAM) TapiEvent,
                (LPARAM) pEvent
               );

    return S_OK;
}
  3. CoUninitialize() Don't manipulate COM objects after calling CoUninitialize. The results are unpredictable and extremely detrimental to producing a healthy application. Some examples in which this can happen are worker threads and C++ destructors that may execute after your code calls CoUninitialize.


Using File Terminals

[This is preliminary documentation and subject to change.]

The file terminals can be used in two ways. The simplest method is to use ITBasicCallControl2::SelectTerminalOnCall to select a file terminal (playback or record) onto a TAPI call object. In this case TAPI takes care of connecting the media streams to the track terminals.

The second method allows an application to have finer control over the mapping of media streams to tracks. In this scenario, the application enumerates the streams available on the call, picks the ones it wants to record (or use for playback), creates (or finds for playback) the corresponding tracks on the file terminal, and selects the tracks on call streams.

For more information, see the following topics:

  • Simple Playback
  • Track-Controlled Playback
  • Simple Record
  • Track-Controlled Record


Simple Playback

[This is preliminary documentation and subject to change.]

To perform simple playback, do the following:

  • Select the File Playback Terminal at the call level.
  • Create the Playback Terminal on the TAPI call.
  • Set properties—file name and type of storage.
  • Call the Start method on the File Playback Terminal to start playback of streams.

The following code snippet illustrates simple playback.

First, use ITBasicCallControl2 to create the terminal for recording. This tells the TSP/MSP that we are going to perform file playback on this call. The TSP/MSP creates a terminal for the application to use, and returns it on success.

ITTerminal *pFilePlaybackTerminal = NULL;

pCall->CreateTerminal(
    CLSID_MediaFilePlaybackTerminal,
    TD_RENDER,
    TAPIMEDIATYPE_MultiTrack,
    &pFileTerminal
    );

Get the ITMediaPlayback interface pointer from the terminal interface and use it to set the file name to play back.

ITMediaPlayback *pMediaPlayback = NULL;
pFilePlaybackTerminal->QueryInterface(IID_ITMediaPlayback, (void**)pMediaPlayback);

// Allocate the array to hold the playlist.
SAFEARRAYBOUND DimensionBounds[1];
DimensionBounds[0].lLbound = 0;
DimensionBounds[0].cElements = 1; // 1 element in the array
SAFEARRAY *pPlayListArray = NULL;
pPlayListArray = SafeArrayCreate(VT_VARIANT, 1, DimensionBounds);

// Allocate the array variant for the playlist.
Variant PlayListVariant;
VariantInint(&PlayListVariant);
PlayListVariant.vt = VT_ARRAY;
VT_ARRAY(PlayListVariant) = pPlayListArray;

// Put the file name into the array.
VARIANT *pvarArrayEntry;
SafeArrayAccessData(pPlayListArray, (void**)&pvarArrayEntry );

// Allocate the string and put it into the array.
VariantInit(pvarArrayEntry);
pvarArrayEntry.vt = VT_BSTR;
VT_BSTR(pvarArrayEntry) = SysAllocString(L"c:\file.asf");

long lArrayPos = 1;
SafeArrayPutElement(pPlayListArray, &lArrayPos, &pvarArrayEntry );
SafeArrayUnaccessData(pPlayListArray);

// Add other file names and/or IStream(s) to the array.

// Pass the array to the terminal.
pMediaPlayback->put_PlayList(pPlayListArray);

// Select the terminal on call.
pCall->SelectTerminalOnCall(pFilePlaybackTerminal);

// Start playback.
pFilePlaybackTerminal->QueryInterface(IID_ImediaControl, (void**)&pMediaControl);
pMediaControl->Start()

// Playback will stop when the file finishes
// or when the application makes the following call.
pMediaControl->Stop();

// Clean up code
pFilePlaybackTerminal->Release();
pMediaControl->Release();
pMediaPlayback->Release()

Assuming the file contains one audio stream and one video stream, and the call has a capture audio stream and a capture video stream, the file will be played back on the two outgoing streams.


Track-Controlled Playback

[This is preliminary documentation and subject to change.]

To perform track-controlled playback, do the following:

  • Select the Track Terminals onto streams.
  • Create the File Playback Terminal.
  • Set properties—file name and type of storage.
  • Using a method on the File Playback Terminal, enumerate File Track Terminals.
  • Enumerate streams on the TAPI call.
  • Select the File Track Terminal on the stream.
  • Call the Start method on the File Playback Terminal to start playback of recorded data to the TAPI streams.


Simple Record

[This is preliminary documentation and subject to change.]

To perform simple recording of streams, do the following:

  • Select the File Record Terminal at the call level
  • Create the File Record Terminal.
  • Set properties—file name and type of storage.
  • Select the File Record Terminal on the call.
  • Call the Start method on the File Record Terminal to start recording of streams.


Track-Controlled Record

[This is preliminary documentation and subject to change.]

To perform track-controlled recording of streams, do the following:

  • Select File Track Terminals onto streams.
  • Create the File Record Terminal.
  • Set properties—file name and type (.asf/.avi/.wav) of storage.
  • Enumerate streams on the TAPI call. For each stream that needs to be recorded:
    • Attempt to create a track of the same media type and direction as the stream.
    • Set track properties (media format). If this is not done, the media type is assumed to be the same as the stream's media type.
    • Select the track on the stream.

      Note that the selected storage (file) type may limit the number of track objects that can be created. For instance, a .wav file can record only one audio stream.

  • Call the Start method on the File Record Terminal to start recording of streams.

If one track is selected on multiple streams, this implies mixing of the streams.


Using Multitrack Terminals and the Default Selection Mechanism

[This is preliminary documentation and subject to change.]

The following code illustrates the use of multitrack terminals and the Default Selection mechanism.

// Get ITBasicCallControl2 on the call object.
ITBasicCallControl2 *pCallControl2 = NULL;

pCallInfo->QueryInterface(IID_ITBasicCallControl2,
    (void**)&pCallControl2);

// Create the terminal for file recording.
ITTerminal *pFileRecordingTerminal = NULL;
pCallControl2->CreateTerminal(CLSID_FileRecordTerminal,
    TD_MULTITRACK,
    TAPIMEDIATYPE_Multitrack,
    &pFileRecordingTerminal);

// Configure the recording terminal.
pFileRecordingTerminal->put_FileName("c:\file.asf");

// Select the recording terminal on the call.
// This will create recording tracks for all streams
// available on the call (best effort--subject to
// limitations by MSPs and the terminal itself).
pCallControl2->SelectTerminalOnCall(pFileRecordingTerminal);

Note Selecting the File Recording Terminal on one stream would cause that stream to be recorded.


Pluggable Terminal Registration

[This is preliminary documentation and subject to change.]

This section describes how pluggable terminals register themselves and signal events, how these events get from the pluggable terminal to TAPI applications, and what interfaces should be implemented.

  • Registry entries
  • Register a pluggable terminal
  • Unregister a pluggable terminal


Registry Entries

[This is preliminary documentation and subject to change.]

The pluggable terminals are classified into Terminal Superclasses. Each Terminal Superclass has an entry in the registry under the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\TerminalManager

Below the Terminal Superclass key are entries for each pluggable terminal within the Terminal Superclass.

The entry for each Terminal Superclass is identified by a Terminal Superclass CLSID. This is a unique identifier for a terminal class. The terminal class has an optional attribute: name, which is a friendly name for the terminal class. Each pluggable terminal is identified by a CLSID Terminal class; that is, a GUID. The attributes for pluggable terminal are stored into pluggable terminal key values. The attributes for a pluggable terminal are the following.

Terminal class | Key name | Public identifier
Name | REG_SZ | Terminal friendly name
Company | REG_SZ | Company name
Version | REG_SZ | Version information
CLSID | REG_SZ | Terminal CLSID (used in COM CoCreateInstance method)
Directions | DWORD | Terminal direction
MediaTypes | DWORD | Terminal media types supported

For a terminal class the attributes are the following.

CLSID | Key name | Public identifier
Name | REG_SZ | Terminal class friendly name


Register a Pluggable Terminal

[This is preliminary documentation and subject to change.]

The registration of a pluggable terminal can be called into the DllRegisterServer function of the component that implements the terminal. The following snippet can be put into the code for DllRegisterServer.

ITPluggableTerminalClassRegistration* pTerminal;
BSTR bstrTerminalSuperclass = SysAllocString(
    _T("{F7438990-D6EB-11d0-82A6-00AA00B5CA1B}"));

BSTR bstrTerminalClass = SysAllocString(
    _T("{AED6483E-3304-11d2-86F1-006008B0E5D2}"));

BSTR bstrTerminalCLSID = SysAllocString(
    _T("{E2F7AEF7-4971-11D1-A671-006097C9A2E8}"));

HRESULT hr;
hr = CoCreateInstance(
    CLSID_PluggableTerminalRegistration,
    NULL,
CLSCTX_INPROCSERVER,
IID_ITPluggableTerminalClassRegistration,
    (void**)&pTerminal);

pTerminal->put_TerminalClass( bstrTerminalClass );
pTerminal->put_CLSIDC( bstrTerminalCLSID );
pTerminal->put_Name( … );
pTerminal->put_Company( … );
pTerminal->put_Version( … );
pTeminal->put_Directions( … );
pTerminal->put_MediaTypes( … );

pTerminal->Add( bstrTerminalSuperclass );


Unregister a Pluggable Terminal

[This is preliminary documentation and subject to change.]

In general, this method will be called from DllUnregisterServer. The following sample code can be put into the code for DllUnregisterServer.

ITPluggableTerminalClassRegistration* pTerminal;
BSTR bstrTermSuperclass = SysAllocString(
    _T("{F7438990-D6EB-11d0-82A6-00AA00B5CA1B}"));

BSTR bstrTerminalClass = SysAllocString(
    _T("{AED6483E-3304-11d2-86F1-006008B0E5D2}"));

HRESULT hr;
hr = CoCreateInstance(
    CLSID_PluggableTerminalRegistration,
    NULL,
CLSCTX_INPROCSERVER,
IID_ITPluggableTerminalClassRegistration,
    (void**)&pTerminal);

pTerminal->put_TerminalClass( bstrTerminalClass );
pTerminal->Delete( bstrTerminalSuperclass);


Registering for Pluggable Terminal Events

[This is preliminary documentation and subject to change.]

The event registration process take place when the terminal is selected by a stream. In the terminal application's implementation of the SelectTerminal method, we can use the ITTerminal interface of the terminal that was attached to the stream, and call QueryInterface to find ITPluggableTerminalEventSinkRegistration.

HRESULT hr = E_FAIL;
ITPluggableTerminalEventSinkRegistration* pEventRegistration = NULL;
hr = pTerminal->QueryInterface(
  IID_ITPluggableTerminalEventSinkRegistration,
  (void**)& pEventRegistration
);

If the QueryInterface call succeeds, we can call the RegisterSink method. For this purpose, we should create an object that implements the ITPluggableTerminalEventSink interface. We pass this interface as a parameter of the RegisterSink method.

ITPluggableTerminalEventSink*    pEventSink;
hr = CreateEventSink( &pEventSink);

if( SUCCEEDED(hr) )
{
  hr = pEventRegistration->RegisterSink( pEventSink );
}

The terminal that implements the ITPluggableTerminalEventSinkRegistration call will store the interface. The pointer will be used when the terminal will fire an event.

The event sink can be unregistered using UnregisterSink.

HRESULT hr = E_FAIL;
ITPluggableTerminalEventSinkRegistration* pEventRegistration = NULL;
hr = pTerminal->QueryInterface(
  IID_ITPluggableTerminalEventSinkRegistration,
  (void**)&pEventHandler
);

if( SUCCEEDED(hr) )
{
    hr = pEventRegistration->UnregisterSink();
}


Code Snippets

The following code snippets briefly illustrate some basic operations. The snippets are written in C++ and Visual Basic. The samples section of the Platform SDK contains full propgrams that can be compiled.

  • Initialize TAPI
  • Select an Address
  • Register Events
  • Select a Terminal
  • Make a Call
  • Receive a Call
  • Create a Simple Conference
  • Transfer a Call


Initialize TAPI

The following code snippet demonstrates creation of the TAPI object.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippet[C++]

// Initialize COM
CoInitializeEx(
    NULL,
    COINIT_MULTITHREADED
    );

// Create a TAPI entry point object.
ITTAPI *gpTapi;
CoCreateInstance(
    CLSID_TAPI,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_ITTAPI,
    (LPVOID *)&gpTapi
    );

// Initialize TAPI
gpTapi->Initialize();

Visual Basic Code Snippet[Visual Basic]

'Usually declared globally
Dim gobjTapi As TAPI

Dim glRegistrationToken As Long
Dim gobjReceivedCallInfo As ITCallInfo
Dim gbSupportedCall As Boolean

'Usually performed during form load
'Create the tapi object.
Set gobjTapi = New TAPI

'Call Initialize before calling any other TAPI function.
Call gobjTapi.Initialize

See Also

ITTAPI::Initialize


Select an Address

The following code snippet demonstrates use of the TAPI object to examine available telephony resources for an address that can handle a specified set of media type requirements. In this snippet, audio and video are the required media.

Before using this code snippet, you must perform the operations in Initialize TAPI.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippet[C++]

// Use the TAPI object to
// enumerate available addresses.
gpTapi->EnumerateAddresses( &pIEnumAddress );

// Locate an address that can support the
// media type the application needs.
while ( S_OK == pEnumAddresses->Next(1, &pAddress, NULL) ) )
{
    // Determine the media support.
    pAddress->QueryInterface(
        IID_ITMediaSupport,
        (void **)&pMediaSupport
        );

    // In this snippet, the required media type is already known.
    // The application can also use the address object to
    // enumerate the media supported, then choose from there.
    pMediaSupport->QueryMediaType(
        TAPIMEDIATYPE_AUDIO|TAPIMEDIATYPE_VIDEO,
        &bSupport
        );
    if (bSupport)
    {
        break;
    }
}
// pAddress is now a usable address.

Visual Basic Code Snippet[Visual Basic]

'pick up the collection of Address objects
Dim gobjAddress As ITAddress
Dim objCollAddresses As ITCollection
Set objCollAddresses = gobjTapi.Addresses

'find address that supports the desired type, nSelectedType
bFound = False
For indexAddr = 1 To objCollAddresses.Count
    Set objCrtAddress = objCollAddresses.Item(indexAddr)
    Set objMediaSupport = objCrtAddress
    Set objAddressCapabilities = objCrtAddress

    If objMediaSupport.QueryMediaType( nSelectedType )
        bFound = True
    End If

    Set objAddressCapabilities = Nothing
    Set objMediaSupport = Nothing
    Set objCrtAddress = Nothing

    If bFound = True Then Exit For
Next indexAddr

Set gobjAddress = objcollAddresses.Item(indexAddr)

'If no errors occurred, gobjAddress is now a usable address.

See Also

ITTAPI::EnumerateAddresses, ITMediaSupport, TAPIMEDIATYPE_ Constants


Register Events

The following code snippets demonstrate implementation of a simple event handler, registration of the main TAPI event interface, setting of the event filter, and registration for call notifications.

Before using this code snippet, you must perform the operations in Initialize TAPI and Select an Address.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippets [C++]

//
// Snippet 1: Implement a simple event handler.
//
HRESULT STDMETHODCALLTYPE
CTAPIEventNotification::Event(
    TAPI_EVENT  TapiEvent,
    IDispatch * pEvent
    )
{
    // AddRef the event so it doesn't go away.
    pEvent->AddRef();

    // Post a message to our own UI thread.
    PostMessage(
        ghDlg,
        WM_PRIVATETAPIEVENT,
        (WPARAM) TapiEvent,
        (LPARAM) pEvent
        );

    return S_OK;
}

//
// Snippet 2: Register the event interface.
//
long                         gulAdvise;  // Globally declared
IConnectionPointContainer   * pCPC;
IConnectionPoint            * pCP;
IUnknown                    * gUnk;

// Get the connection point container
// interface pointer from the TAPI object.
gpTapi->QueryInterface(
     IID_IConnectionPointContainer,
     (void **)&pCPC
     );

// Get the ITTAPIEventNOtification interface
// pointer from the container.
pCPC->FindConnectionPoint(
     IID_ITTAPIEventNotification,
     &pCP
     );

pCPC->Release();

// Create a private event notification object.
pTapiEventNotification = new CTAPIEventNotification;

pTAPIEventNotification->QueryInterface(
    IID_IUnknown,
    (void **)&pUnk
    );

// Call the advise method to give TAPI
// the IUnknown pointer for the event handler.
pCP->Advise(
     pUnk,
     (ULONG *)&gulAdvise
     );

pCP->Release();

//
// Snippet 3: Set the event filter.
//
// Assume we are interested
// only in call-related events.
gpTapi->put_EventFilter(
   TE_CALLNOTIFICATION | TE_CALLSTATE | TE_CALLMEDIA
   );

//
// Snippet 4: Register an address with TAPI
// for call notifications. Assume we are interested
// in video and audio calls, and that pAddress
// is a pointer to the ITAddress interface of
// an address that can handle both media types.

long glRegister; // Globally declared

gpTapi->RegisterCallNotifications(
    pAddress,
    VARIANT_TRUE,   // monitor privileges
    VARIANT_TRUE,   // owner privileges
    TAPIMEDIATYPE_AUDIO|TAPIMEDIATYPE_VIDEO,
    gulAdvise,      // As returned by Advise
    &glRegister
    );

Visual Basic Code Snippet [Visual Basic]

'Usually declared globally
Dim WithEvents gobjTapiWithEvents As TAPI
Attribute gobjTapiWithEvents.VB_VarHelpID = -1
Dim glRegistrationToken As Long

'Usually performed at the same time
'as TAPI initialization
Const TAPI3_CALL_EVENTS = _
    TE_CALLMEDIA Or _
    TE_CALLNOTIFICATION Or _
    TE_CALLSTATE

'Set the EventFilter to accept all defined TAPI events.
gobjTapi.EventFilter = TAPI3_CALL_EVENTS

'Register the outgoing interface (the one that will actually
'receive and process the events).
Set gobjTapiWithEvents = gobjTapi
Dim fOwner As Boolean, fMonitor As Boolean
Dim lMediaTypes As Long, lCallbackInstance As Long

'fOwner = True ensures that the application receives incoming calls
'and their call state events.
fOwner = True
fMonitor = False
lMediaTypes = TAPIMEDIATYPE_AUDIO
lCallbackInstance = 1

glRegistrationToken = gobjTapi.RegisterCallNotifications( _
    gobjAddress, _
    fMonitor, _
    fOwner, _
    lMediaTypes, _
    lCallbackInstance
    )

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITTAPI::put_EventFilter, TAPIMEDIATYPE_ Constants, ITTAPI::RegisterCallNotifications


Select a Terminal

The following code snippet demonstrates selecting terminals onto streams associated with a call.

Before using this code snippet, you must perform the operations in Initialize TAPI and Select an Address.

Also, this snippet requires that the application already have a pointer to the ITBasicCallControl interface of either an incoming or outgoing call. See Make a Call or Receive a Call for code snippets on how to obtain this pointer.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippet[C++]

// pAddress is an ITAddress interface pointer.
// pBasicCall is an ITBasicCallControl interface pointer.

// Get the ITStreamControl interface.
ITStreamControl * pStreamControl;
pBasicCall->QueryInterface(
    IID_ITStreamControl,
    (void **) &pStreamControl
    );

// Enumerate the streams and select
// terminals onto them.
IEnumStream * pEnumStreams;
ITStream    * pStream;
pStreamControl->EnumerateStreams(&pEnumStreams);
while ( S_OK == pEnumStreams->Next(1, &pStream, NULL) )
    {
        // Get the media type and direction of this stream.
        long                lMediaType;
        TERMINAL_DIRECTION  dir;
        pStream->get_MediaType( &lMediaType );
        pStream->get_Direction( &dir );

        // Create the default terminal for this media type
        // and direction.
        //   If lMediaType == TAPIMEDIATYPE_VIDEO and
        //   dir == TD_RENDER, a dynamic video render terminal
        //   is required. Please see Incoming.cpp in
        //   the samples section of the SDK.
        // For all other terminals, get the default
        // static terminal.
        ITTerminal * pTerminal;
        ITTerminalSupport * pTerminalSupport;
        pAddress->QueryInterface(
            IID_ITTerminalSupport,
            (void **)&pTerminalSupport
            );
        pTerminalSupport->GetDefaultStaticTerminal(
            lMediaType,
            dir,
            pTerminal
            );
        // Select the terminal on the stream.
        pStream->SelectTerminal(pTerminal);
    }

Visual Basic Code Snippet[Visual Basic]

'query for ITBasicCallControl, the call control interface
Dim objCallControl As ITBasicCallControl
Set objCallControl = gobjReceivedCallInfo

'query ITTerminalSupport from Address object
Dim objTerminalSupport As ITTerminalSupport
Set objTerminalSupport = gobjAddress

Dim objTerminal As ITTerminal
Set objTerminal = objTerminalSupport.GetDefaultStaticTerminal _
    lMediaType, dir)

'release not needed objects
Set objTerminalSupport = Nothing

'Select the terminal before answering
'we'll need the ITStreamControl interface for doing this.

Dim objStreamControl As ITStreamControl
Set objStreamControl = objCallControl

If Not (objStreamControl Is Nothing) Then
    Dim objITCollStreams As ITCollection

    Set objITCollStreams = objStreamControl.Streams

    Dim nIndex As Long, objCrtStream As ITStream

    For nIndex = 1 To objITCollStreams.Count
        Set objCrtStream = objITCollStreams.Item(nIndex)
        If objCrtStream.MediaType = lMediaType  Then
            If objCrtStream.Direction = dir Then
                Call objCrtStream.SelectTerminal(objTerminal)
            End If
        End If
        Set objCrtStream = Nothing
    Next nIndex

    Set objITCollStreams = Nothing
    Set objStreamControl = Nothing
End If

See Also

ITAddress, ITBasicCallControl, ITStreamControl, ITStream, IEnumStream, ITTerminal, ITTerminalSupport


Make a Call

The following code snippet demonstrates creating a call object, discovering the streams associated with the call, selecting and creating appropriate terminals, selecting the terminals onto the streams, and completing the connection.

Before using this code snippet, you must perform the operations in Initialize TAPI and Select an Address.

Also, you must perform the operations illustrated in Select a Terminal following the call to ITAddress::CreateCall.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippet[C++]

// Specify the destination address.
//
// szAddressToCall and
// dwAddressType have been
// retrieved from a user interface.
ITBasicCallControl * pBasicCall
bstrAddressToCall = SysAllocString( szAddressToCall );
pAddress->CreateCall(
    bstrAddressToCall,
    dwAddressType,
    &pBasicCall
 );

// Create the required terminals for this call.
{
    // See the Select a Terminal code snippet.
}

// Make the connection.
pBasicCall->Connect( TRUE );

Visual Basic Code Snippet[Visual Basic]

Set gobjCall = gobjOrigAddress.CreateCall(_
    strDestAddress, nSelectedType, lMediaTypes)

'Create the required terminals for this call.
{
    'See the Select a Terminal code snippet.
}

'Connect the call; False means that the call is made asynchronously.
gobjCall.Connect (False)

See Also

ITAddress::CreateCall, ITBasicCallControl, ITBasicCallControl::Connect


Receive a Call

The following code snippet demonstrates handling of new call notifications, such as finding or creating appropriate terminals to render the media. This snippet is a portion of the switch statement an application must implement for event handling. The code itself may be contained in the implementation of ITTAPIEventNotification::Event, or the Event method may post a message to a worker thread that contains the switch.

Before using this code snippet, you must perform the operations in Initialize TAPI, Select an Address, and Register Events.

Also, you must perform the operations illustrated in Select a Terminal following the retrieval of the ITBasicCallControl and ITAddress interface pointers.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippet[C++]

// pEvent is an IDispatch pointer for the
// ITCallNotificationEvent interface of the
// call object created by TAPI, and is passed
// into the event handler by TAPI.

Case TE_CALLNOTIFICATION:
{
    // Get the ITCallNotification interface.
    ITCallNotificationEvent * pNotify;
    pEvent->QueryInterface(
        IID_ITCallNotificationEvent,
        (void **)&pNotify
        );

    // Get the ITCallInfo interface.
    ITCallInfo * pCallInfo;
    pNotify->get_Call( &pCallInfo);

    // Get the ITBasicCallControl interface.
    ITBasicCallControl *    pBasicCall;
    pCallInfo->QueryInterface(
        IID_ITBasicCallControl,
        (void**)&pBasicCall
        );

    // Get the ITAddress interface.
    ITAddress * pAddress;
    pCallInfo->get_Address( &pAddress );

    // Create the required terminals for this call.
    {
        // See the Select a Terminal code snippet.
    }
    // Complete incoming call processing.
    pBasicCall->Answer();
}

Visual Basic Code Snippet[Visual Basic]

' pEvent is an IDispatch pointer for the
' ITCallNotificationEvent interface of the
' call object created by TAPI, and is passed
' into the event handler by TAPI.
If TapiEvent = TE_CALLNOTIFICATION Then
    ' Get the ITCallNotification interface.
    Dim objCallNotificationEvent As ITCallNotificationEvent
    Set objCallNotificationEvent = pEvent

   'query ITCallInfo interface for the new call, and store it
    Dim gobjReceivedCallInfo As ITCallInfo
    Set gobjReceivedCallInfo = objCallNotificationEvent.Call

    ' Get the ITBasicCallControl interface.
    Dim objCallControl As ITBasicCallControl
    Set objCallControl = gobjReceivedCallInfo

    ' Create the required terminals for this call.
    ' See the Select a Terminal code snippet.

    'Answer
    objCallControl.Answer
End If

See Also

Events, ITTAPIEventNotification, ITTAPI::RegisterCallNotifications, ITCallNotificationEvent, ITCallInfo, ITBasicCallControl, ITTerminalSupport


Create a Simple Conference

The following code snippet demonstrates the creation of a simple conference call. For information on IP multicast multimedia video conferencing, please see About Rendezvous IP Telephony Conferencing.

Before using this code snippet, a call must be in progress, and you must perform the operations in Make a Call or Receive a Call have been performed.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippet

// From elsewhere in your code, you have obtained
// pBasicCall and pCallInfo, which are pointers to the
// ITBasicCallControl and ITCallInfo interfaces
// of a call currently in progress.
// pAddress is an ITAddress pointer.

// Create a consultation call for the conference.
ITBasicCallControl *pConsultCall;
pAddress->CreateCall(
    bstrAddressToCall,
    dwAddressType,
    &pConsultCall
    );

// Move the consultation call into your conference.
// Note: If a CallHub object does not already
// exist, TAPI will create it.
pBasicCall->Conference(
          pConsultCall,
          VARIANT_TRUE
          );

// Finish the creation of the conference.
pConsultCall->Finish(FM_ASCONFERENCE);

// Assuming the Finish method succeeds,
// the consultation call (pConsultCallA)
// may transition to the CS_DISCONNECTED state
// or may remain connected, depending on the
// service provider.
//
// Get the ITCallHub interface pointer.
ITCallHub *pCallHub;
pCallInfo->get_CallHub( pCallHub );

// You can use the ITCallHub interface
// to obtain additional information on
// the conference. Specific capabilities
// depend on the TSP/MSP being used.

See Also

ITCallInfo, ITBasicCallControl, ITCallHub


Transfer a Call

The following code snippet demonstrates a call transfer.

Before using this code snippet, a call must be in progress, and you must perform the operations in Make a Call or Receive a Call.

Note This snippet does not have the error checking and releases appropriate for real code.

C++ Code Snippet

// From elsewhere in your code, you have obtained
// pAddress and pBasicCall, which are pointers to the
// ITAddress and ITBasicCallControl interfaces
// of the call in progress that will be transferred.

// Create the call object for transfer.
// bstrAddressToCall and dwAddressType
// have been retrieved from a UI.
ITBasicCallControl * pConsultCall
pAddress->CreateCall(
    bstrAddressToCall,
    dwAddressType,
    &pConsultCall
    );

// Start the transfer.
pBasicCall->Transfer(
    pConsultCall,
    VARIANT_TRUE
    );

// Depending on the service provider,
// additional operations may be available
// or required.

// Finish the transfer.
pConsultCall->Finish(FM_ASTRANSFER);

// The consultation call transitions to CS_DISCONNECTED.
// The objects associated with pConsultCall and
// pBasicCall can be released immediately or
// used for information purposes and released later.

See Also

ITCallInfo, ITBasicCallControl, ITCallHub


Call and Media Control Reference

The Call and Media Control reference material contains information on interfaces, methods, enumerators, and types used in TAPI 3.0 call setup and control.

You may also wish to search the Platform SDK for information on DirectShow™ and the Component Object Model (COM). TAPI 3.0 uses DirectShow filters and filter managers to control the media stream following connection setup. COM is the basic coding model for TAPI 3.0, and familiarity with it is assumed throughout this document.

Call and Media Control Quick Reference

Call and Media Control COM Interfaces

Call and Media Control Constants

Call and Media Control Enumerations


Call and Media Control Quick Reference

The following table lists TAPI version 3.0 COM interfaces by category in order of importance. The interfaces are grouped according to TAPI 3.0's five basic call control objects: TAPI, Address, Terminal, Call, and CallHub. Remaining interfaces are grouped according to Automatic Call Distribution (ACD) interfaces, which provide call-center functionality; enumerator interfaces, and stand-alone objects.

Interface groupings | Description
TAPI Object Interfaces | The TAPI object is the main object for TAPI 3.0.
Address Object Interfaces | The Address object represents an entity that can make or receive calls. The associated interfaces and methods allow an application to get and set information concerning the address, such as whether it has caller ID support.
Terminal Object Interfaces | The Terminal object represents the sink or source at the termination or origination point of a call. The associated interfaces and methods allow an application to get and set information concerning the terminal, such as whether it is currently in use.
Call Object Interfaces | The Call object represents a call and is created when a call comes into existence. The associated interfaces and methods get and set information concerning the call, such as current call state.
Phone Object Interfaces | TBD
IPConf MSP Interfaces | The IP conferencing MSP implements several interfaces for participant control that are exposed on the call object.
CallHub Object Interfaces | The CallHub object represents a third-party view of a multi-party call. The associated interfaces and methods get and set information concerning the call, such as whether the call hub is active.
Enumerator Interfaces | COM-standard enumerator interfaces.
Event Interfaces | The event interfaces are also shown with their object or function groupings.
Stand-Alone Objects | The TAPI 3.0 miscellaneous stand-alone objects provide interfaces and methods for operations such as assisted telephony or event handling.


TAPI Object Interfaces

The TAPI Object is the main object for TAPI 3.0.

The ITTAPIObjectEvent interface is not directly exposed on the TAPI Object, but is tightly related to it and is listed here for reference convenience.

Interfaces | Description
ITTAPI | Primary TAPI 3.0 interface.
ITTAPI2 | Derives from ITTAPI; provides additional methods that support phone devices.
ITTAPIEventNotification | Outgoing interface used to receive asynchronous information about TAPI 3.0 events.
ITTAPICallCenter | Provides an entry interface into call center controls.
ITTAPIObjectEvent | Provides methods to retrieve information concerning TAPI object events.
ITTAPIObjectEvent2 | Extends ITTAPIObjectEvent; provides a method to retrieve a pointer to the phone object that caused the TAPI object event.


Address Object Interfaces

Address objects are entities that can make or receive calls. The related interfaces and methods allow an application to get and set information concerning an address, such as whether the address has caller ID support.

The ITAddressEvent, ITAddressTranslationInfo, ITCallingCard, ITForwardInformation, ITLocationInfo, and IEnumAddress interfaces are not directly exposed on the Address Object, but are tightly related to it and are listed here for reference convenience.

Interface | Description
ITAddress | Acts as base interface for the Address object.
ITAddress2 | Derives from ITAddress; provides additional methods that support phone devices.
ITAddressCapabilities | Gets information concerning an address's capabilities.
ITAddressEvent | Provides information concerning address events.
ITAddressTranslation | Performs address translation.
ITAddressTranslationInfo | Gets address translation information.
ITCallingCard | Provides methods to retrieve calling card information.
ITForwardInformation | Provides methods for setting up and implementing call forwarding.
ITLegacyAddressMediaControl | Supports legacy applications that require direct access to a device and its configuration.
ITLegacyAddressMediaControl2 | Extends ITLegacyAddressMediaControl by allowing the configuration of parameters related to line devices.
ITLocationInfo | Gets information related to the location of the calling party.
ITMediaSupport | Gets information concerning an address's media support capabilities.
ITTerminalSupport | Gets information on available terminals and provides a method to create additional terminals.
IEnumAddress | Enumerates ITAddress.
IEnumCallingCard | Enumerates ITCallingCard.

If the address is a Wave MSP address, the ITLegacyWaveSupport interface is also exposed on the Address object.


Terminal Object Interfaces

The Terminal Object interfaces give an application access to manipulate devices used to create or receive media streams.

These interfaces are implemented by an MSP and will not be available if the address is not supported by a media service provider. If an associated MSP exists, the ITTerminalSupport interface is exposed on the Address Object.

The IEnumTerminal and IEnumTerminalClass interfaces are not directly exposed on the Terminal Object, but are tightly related to it and are listed here for reference convenience.

Interface | Description
ITTerminal | Base interface for the Terminal Object. It provides methods for obtaining information such as terminal class and media supported.
ITAMMediaFormat | Sets and gets DirectShow media format.
ITBasicAudioTerminal | Provides methods to set and get standard audio terminal characteristics, such as volume.
IEnumTerminal | Enumerates ITTerminal.
IEnumTerminalClass | Enumerates Terminal Class.
IEnumPluggableSuperclassInfo | Enumerates ITPluggableTerminalSuperclassInfo.
IEnumPluggableTerminalClassInfo | Enumerates ITPluggableTerminalClassInfo.
ITFileTrack | Retrieves and sets information concerning file terminal tracks.
ITASRTerminalEvent | Retrieves the description of Automatic Speech Recognition terminal events.
ITFileTerminalEvent | Retrieves the description of file terminal events.
ITMultiTrackTerminal | Enumerates, creates, or removes tracks on multitrack terminals.

ITPluggableTerminalClassInfo | Retrieves information concerning a pluggable terminal.
ITPluggableTerminalClassRegistration | Creates, modifies, or deletes the registry entry for a pluggable terminal.
ITPluggableTerminalInitialization | Performs primary terminal object creation for pluggable terminals, allowing the Terminal Manager to initialize the terminal.
ITPluggableTerminalSuperclassInfo | Retrieves the name and CLSID of a pluggable terminal class.
ITPluggableTerminalSuperclassRegistration | Retrieves and sets information about a terminal superclass (name and CLSID).
ITPluggableTerminalEventSink | Notifies client applications about changes in a pluggable terminal.
ITPluggableTerminalEventSinkRegistration | Registers and unregisters a client application for notification about pluggable terminal events.

ITTTSTerminalEvent | Retrieves the description of text-to-speech (TTS) terminal events.
ITToneDetectionEvent | Retrieves information about a tone detection event.
ITToneTerminalEvent | Retrieves the description of tone terminal events.


Call Object Interfaces

The Call object is created when a call comes into existence. Associated interfaces get and set information concerning the call.

Enumerator and event interfaces are not directly exposed on the Call Object, but are listed here for reference convenience.

The ITCallNotificationEvent, ITCallInfoChangeEvent, ITCallStateEvent, ITCallMediaEvent and IEnumTerminalClass interfaces are not directly exposed on the Call Object, but are tightly related to it and are listed here for reference convenience.

Interface | Description
ITCallInfo | Provides information concerning a Call object, such as call state or terminals in use.
ITCallInfo2 | Extends ITCallInfo by providing methods to set event filtering on a per-call basis.
ITBasicCallControl | Used to connect, answer, and perform basic telephony operations on a call object.
ITBasicCallControl2 | Extends ITBasicCallControl by providing methods to select a terminal onto a call.
ITCallNotificationEvent | Notification interface for ITCallInfo.
ITCallInfoChangeEvent | Notification interface for changes in call information.
ITCallStateEvent | Gets information concerning a call event.
ITCallMediaEvent | Gets information concerning a call media event.
ITCustomTone | Provides methods to control the custom tones possible with some phone sets.
ITDetectTone | Provides methods to specify the tones and tone characteristics that generate tone events.
ITLegacyCallMediaControl | Supports legacy applications that must communicate directly with a device.
ITLegacyCallMediaControl2 | Extends ITLegacyCallMediaControl by providing methods for tone detection and generation.
IEnumCall | Enumerates ITCallInfo.


Phone Object Interfaces

[This is preliminary documentation and subject to change.]

TBD

Interface | Description
ITPhone | Allows access to the phone device at a level comparable to that available with the TAPI 2.x C API.
ITAutomatedPhoneControl | Provides methods for automated control of a phone's tones and rings, and for automated call handling based on a phone's hookswitch state.
ITPhoneEvent | Retrieves the description of phone events.
IEnumPhone | Enumerates ITPhone.


IPConf MSP Interfaces

The IP conferencing MSP implements several provider-specific interfaces for participant control. These interfaces are exposed on the call object, if this MSP is associated with the call.

The ITParticipantEvent and IEnumParticipant interfaces are stand-alone objects, and are listed here for reference convenience.

Interface | Description
IMulticastControl | Allows an application to set and get the loopback mode (MULTICAST_LOOPBACK_MODE) for a multicast conference object.
ITParticipant | Allows an application to retrieve information on conference participants, and get pointers to the streams associated with those participants.
ITParticipantControl | Allows an application to retrieve pointers to the participants in a conference.
ITParticipantEvent | Allows an application to retrieve event information concerning a conference participant.
IEnumParticipant | Enumerates ITParticipant.


CallHub Object Interfaces

The CallHub object exposes methods that retrieve information concerning participants in a multi-party call.

The ITCallHubEvent and IEnumCallHub interfaces are not directly exposed on the CallHub Object, but are tightly related to it and are listed here for reference convenience.

Interface | Description
ITCallHub | Provides methods to retrieve information concerning a CallHub object.
ITCallHubEvent | Used to acquire information concerning CallHub events.
IEnumCallHub | Enumerates ITCallHub.


Enumerator Interfaces

The following interfaces enumerate TAPI 3.0 elements according to COM standards. These interfaces constitute stand-alone objects, and are also summarized with their related objects.

Interface | Item enumerated
IEnumAddress | ITAddress
IEnumBstr | BSTR strings, such as those returned by ITAddressCapabilities::EnumerateDeviceClasses.
IEnumCall | ITCallInfo
IEnumCallHub | ITCallHub
IEnumCallingCard | ITCallingCard
IEnumLocation | ITLocationInfo
IEnumParticipant | ITParticipant
IEnumPhone | ITPhone
IEnumPluggableSuperclassInfo | ITPluggableTerminalSuperclassInfo
IEnumPluggableTerminalClassInfo | ITPluggableTerminalClassInfo
IEnumQueue | ITQueue
IEnumTerminal | ITTerminal
IEnumTerminalClass | Terminal Class


Stand Alone Objects

Platform SDK: TAPI

Stand-Alone Objects

TAPI 3.0 involves a number of objects that are independent of its five main TAPI objects (TAPI, Address, Call, CallHub, and Terminal). Event Interfaces and Enumerator Interfaces are stand-alone objects, and are summarized separately. The following summarizes non-event and non-enumerator stand-alone interfaces.

Interface | Description
ITCollection | Provides methods to allow Automation client applications such as Visual Basic to retrieve collection information.
ITCollection2 | Extends ITCollection by providing additional methods for modifying collections.
IDispatch | Standard COM interface for implementing Automation.
IUnknown | Standard COM interface for getting pointers to object interfaces.
ITDispatchMapper | Allows an application to retrieve the dispatch pointer of another interface on an object, given a current IDispatch pointer. Useful for some scripting languages.
ITRequest | Provides methods that allow a TAPI 3.0 application to use Assisted Telephony.

ITMediaControl | Starts, stops, and pauses current actions, such as a playback.
ITMediaPlayback | Provides playback-specific methods that allow an application to perform such operations as setting the list of files to play and changing the playback speed.
ITMediaRecord | Provides recording-specific methods that allow an application to perform such operations as setting the names of files to record and changing the duration of a recording.

ITScriptableAudioFormat | Retrieves the audio format from, or sets the audio format for, a track.
ITStaticAudioTerminal | Provides methods on static audio terminal objects that are needed to support phone devices. TAPI 3.1 MSPs must expose this interface on all static audio terminals.


Event Interfaces

The event (notification) interfaces allow a TAPI 3.0 application to respond to asynchronous events.

You must call the ITTAPI::put_EventFilter method and set an event filter mask to enable reception of request events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events.

Please see the Events overview for a description of how an application ensures reception of notifications. See the individual interfaces listed in the following table for more information about setting a filter mask for individual event types.

Interface | Description
ITAddressEvent | Retrieves the description of address events.
ITASRTerminalEvent | Retrieves the description of Automatic Speech Recognition terminal events.
ITCallHubEvent | Retrieves the description of CallHub events.
ITCallInfoChangeEvent | Retrieves the description of call information change events.
ITCallMediaEvent | Retrieves the description of call media events.
ITCallNotificationEvent | Retrieves the description of call notification events.
ITCallStateEvent | Retrieves the description of call state events.
ITDigitDetectionEvent | Retrieves information about DTMF digit events during a call.
ITDigitGenerationEvent | Retrieves information about calls that require the generation of DTMF digits.
ITDigitsGatheredEvent | Retrieves data related to an application's digit-gathering request.
ITFileTerminalEvent | Retrieves the description of file terminal events.
ITParticipantEvent | Retrieves the description of conference participant events.
ITPhoneEvent | Retrieves the description of phone events.
ITQOSEvent | Retrieves the description of quality of service (QOS) events.
ITQueueEvent | Retrieves the description of Automatic Call Distribution (ACD) queue events.
ITRequestEvent | Retrieves the description of Assisted Telephony request events.
ITTAPIObjectEvent | Retrieves the description of TAPI object events.
ITTAPIObjectEvent2 | Extends ITTAPIObjectEvent; retrieves a pointer to the phone object that caused the TAPI object event.
ITToneDetectionEvent | Retrieves information about a tone detection event.
ITToneTerminalEvent | Retrieves the description of tone terminal events.
ITTTSTerminalEvent | Retrieves the description of text-to-speech (TTS) terminal events.

ITPluggableTerminalEventSink | Notifies client applications about changes in a pluggable terminal.
ITPluggableTerminalEventSinkRegistration | Registers and unregisters a client application for notification about pluggable terminal events.


Call and Media Control Constants

TAPI functions, methods, and structures may use the following constants:

  • LINEADDRESSTYPE_
  • TAPI_DIGITMODE_
  • TAPIMEDIATYPE_
  • TAPI_E_
  • TAPIPROTOCOL_
  • Terminal Class


LINEADDRESSTYPE_ Constants

The address type identifies address format, such as standard phone number or e-mail address. Only applications that negotiate TAPI version 3.0 or higher can use address types.

LINEADDRESSTYPE_PHONENUMBER
0x00000001
Address type is a standard phone number.
LINEADDRESSTYPE_SDP
0x00000002
Address type is Session Description Protocol (SDP) conference.
LINEADDRESSTYPE_EMAILNAME
0x00000004
Address type is an e-mail name.
LINEADDRESSTYPE_DOMAINNAME
0x00000008
Address type is a domain name.
LINEADDRESSTYPE_IPADDRESS
0x00000010
Address type is an IP address.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi.h.


TAPI_E_ Constants

TAPI methods and functions may return a TAPI_E_ constant. These constants indicate the outcome of an API call.

The 32 bit values are laid out as follows:

3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
---+-+-+-----------------------+-------------------------------+
Sev|C|R|     Facility          |               Code            |
---+-+-+-----------------------+-------------------------------+
Section | Description
Sev - Severity Code | 00 - Success
 | 01 - Informational
 | 10 - Warning
 | 11 - Error
C | Customer code flag
R | Reserved bit
Facility | Facility code
Code | Facility's status code

TAPI_E_NOTENOUGHMEMORY
The buffer passed in to this method was not big enough.
((HRESULT)0x80040001L)
TAPI_E_NOITEMS
No items exist that match the request.
((HRESULT)0x80040002L)
TAPI_E_NOTSUPPORTED
This method is not supported.
((HRESULT)0x80040003L)
TAPI_E_INVALIDMEDIATYPE
An invalid media type was passed in.
((HRESULT)0x80040004L)
TAPI_E_OPERATIONFAILED
The operation failed for an unspecified reason.
((HRESULT)0x80040005L)
TAPI_E_ALLOCATED
The device is already in use.
((HRESULT)0x80040006L)
TAPI_E_CALLUNAVAIL
No call appearance is available.
((HRESULT)0x80040007L)
TAPI_E_COMPLETIONOVERRUN
Too many call completions are outstanding.
((HRESULT)0x80040008L)
TAPI_E_CONFERENCEFULL
The conference is full and more members cannot be added.
((HRESULT)0x80040009L)
TAPI_E_DIALMODIFIERNOTSUPPORTED
The dial modifier is not supported.
((HRESULT)0x8004000AL)
TAPI_E_INUSE
The device is already in use.
((HRESULT)0x8004000BL)
TAPI_E_INVALADDRESS
The address is invalid or not properly formatted. For example, if address type is LINEADDRESSTYPE_PHONENUMBER, this error code would mean that the data entered did not appear to be a real phone number.
((HRESULT)0x8004000CL)
TAPI_E_INVALADDRESSSTATE
The operation is not permitted in the current address state.
((HRESULT)0x8004000DL)
TAPI_E_INVALCALLPARAMS
The LINECALLPARAMS structure is invalid.
((HRESULT)0x8004000EL)
TAPI_E_INVALCALLPRIVILEGE
The call privilege is invalid.
((HRESULT)0x8004000FL)
TAPI_E_INVALCALLSTATE
The operation is not permitted in the current call state.
((HRESULT)0x80040010L)
TAPI_E_INVALCARD
The calling card is invalid.
((HRESULT)0x80040011L)
TAPI_E_INVALCOMPLETIONID
The call completion ID is invalid.
((HRESULT)0x80040012L)
TAPI_E_INVALCOUNTRYCODE
The country code is invalid.
((HRESULT)0x80040013L)
TAPI_E_INVALDEVICECLASS
The device class identifier is invalid.
((HRESULT)0x80040014L)
TAPI_E_INVALDIALPARAMS
The dialing parameters are invalid.
((HRESULT)0x80040015L)
TAPI_E_INVALDIGITS
The digits are invalid.
((HRESULT)0x80040016L)
TAPI_E_INVALGROUPID
The group pickup ID is invalid.
((HRESULT)0x80040017L)
TAPI_E_INVALLOCATION
The location ID is invalid.
((HRESULT)0x80040018L)
TAPI_E_INVALMESSAGEID
The message ID is invalid.
((HRESULT)0x80040019L)
TAPI_E_INVALPARKID
The park ID is invalid.
((HRESULT)0x8004001AL)
TAPI_E_INVALRATE
The rate is invalid.
((HRESULT)0x8004001BL)
TAPI_E_INVALTIMEOUT
The timeout value is invalid.
((HRESULT)0x8004001CL)
TAPI_E_INVALTONE
The tone is invalid.
((HRESULT)0x8004001DL)
TAPI_E_INVALLIST
An invalid list was passed as a parameter.
((HRESULT)0x8004001EL)
TAPI_E_INVALMODE
An invalid mode was passed as a parameter.
((HRESULT)0x8004001FL)
TAPI_E_NOCONFERENCE
The call is not part of a conference.
((HRESULT)0x80040020L)
TAPI_E_NODEVICE
The device was removed, or the device class is not recognized.
((HRESULT)0x80040021L)
TAPI_E_NOREQUEST
No Assisted Telephony requests are pending.
((HRESULT)0x80040022L)
TAPI_E_NOTOWNER
The application does not have OWNER privilege on the call.
((HRESULT)0x80040023L)
TAPI_E_NOTREGISTERED
The application is not registered to handle requests.
((HRESULT)0x80040024L)
TAPI_E_REQUESTOVERRUN
The request queue is already full.
((HRESULT)0x80040025L)
TAPI_E_TARGETNOTFOUND
The call handoff failed because the specified target was not found.
((HRESULT)0x80040026L)
TAPI_E_TARGETSELF
No higher priority target exists for the call handoff.
((HRESULT)0x80040027L)
TAPI_E_USERUSERINFOTOOBIG
The amount of user-user information exceeds the maximum permitted.
((HRESULT)0x80040028L)
TAPI_E_REINIT
The operation cannot be completed until all TAPI applications shut down and reinitialize.
((HRESULT)0x80040029L)
TAPI_E_ADDRESSBLOCKED
You are not permitted to call this number.
((HRESULT)0x8004002AL)
TAPI_E_BILLINGREJECTED
The calling card number or other billing information was rejected.
((HRESULT)0x8004002BL)
TAPI_E_INVALFEATURE
The device-specific feature is invalid.
((HRESULT)0x8004002CL)
TAPI_E_INVALBUTTONLAMPID
The button or lamp ID is invalid.
((HRESULT)0x8004002DL)
TAPI_E_INVALBUTTONSTATE
The button state is invalid.
((HRESULT)0x8004002EL)
TAPI_E_INVALDATAID
The data segment ID is invalid.
((HRESULT)0x8004002FL)
TAPI_E_INVALHOOKSWITCHDEV
The hookswitch device ID is invalid.
((HRESULT)0x80040030L)
TAPI_E_DROPPED
The call was disconnected.
((HRESULT)0x80040031L)
TAPI_E_NOREQUESTRECIPIENT
No program is available to handle the request.
((HRESULT)0x80040032L)
TAPI_E_REQUESTQUEUEFULL
The queue of call requests is full.
((HRESULT)0x80040033L)
TAPI_E_DESTBUSY
The called number is busy.
((HRESULT)0x80040034L)
TAPI_E_DESTNOANSWER
The called party does not answer.
((HRESULT)0x80040035L)
TAPI_E_DESTUNAVAIL
The called number could not be reached.
((HRESULT)0x80040036L)
TAPI_E_REQUESTFAILED
The request failed for unspecified reasons.
((HRESULT)0x80040037L)
TAPI_E_REQUESTCANCELLED
The request was cancelled.
((HRESULT)0x80040038L)
TAPI_E_INVALPRIVILEGE
The application's privilege level is invalid for the current operation.
((HRESULT)0x80040039L)
TAPI_E_INVALIDDIRECTION
The TERMINAL_DIRECTION passed in was invalid.
((HRESULT)0x8004003AL)
TAPI_E_INVALIDTERMINAL
The terminal passed in was invalid for this operation.
((HRESULT)0x8004003BL)
TAPI_E_INVALIDTERMINALCLASS
The terminal class is invalid.
((HRESULT)0x8004003CL)
TAPI_E_NODRIVER
The service provider was removed.
((HRESULT)0x8004003DL)
TAPI_E_MAXSTREAMS
The maximum number of streams was reached.
((HRESULT)0x8004003EL)
TAPI_E_NOTERMINALSELECTED
The operation could not be performed because it requires terminals to be selected.
((HRESULT)0x8004003FL)
TAPI_E_TERMINALINUSE
The operation could not be performed because the terminal is in use.
((HRESULT)0x80040040L)
TAPI_E_NOTSTOPPED
The operation could not be performed because it requires the stream to be stopped.
((HRESULT)0x80040041L)
TAPI_E_MAXTERMINALS
The maximum number of terminals has been reached.
((HRESULT)0x80040042L)
TAPI_E_INVALIDSTREAM
The stream passed in was invalid for this operation.
((HRESULT)0x80040043L)
TAPI_E_TIMEOUT
The call failed because of a timeout. The timeout interval is two minutes.
((HRESULT)0x80040044L)
TAPI_E_CALLCENTER_GROUP_REMOVED
The ACD Proxy has removed this group. Operations on this object are invalid.
((HRESULT)0x80040045L)
TAPI_E_CALLCENTER_QUEUE_REMOVED
The ACD Proxy has removed this queue. Operations on this object are invalid.
((HRESULT)0x80040046L)
TAPI_E_CALLCENTER_NO_AGENT_ID
The Agent object was created with CreateAgent and has no ID. If an ID is needed, use CreateAgentWithID.
((HRESULT)0x80040047L)
TAPI_E_CALLCENTER_INVALAGENTID
The agent ID is invalid.
((HRESULT)0x80040048L)
TAPI_E_CALLCENTER_INVALAGENTGROUP
The agent group is invalid.
((HRESULT)0x80040049L)
TAPI_E_CALLCENTER_INVALPASSWORD
The agent password is invalid.
((HRESULT)0x8004004AL)
TAPI_E_CALLCENTER_INVALAGENTSTATE
The agent state is invalid.
((HRESULT)0x8004004BL)
TAPI_E_CALLCENTER_INVALAGENTACTIVITY
The agent activity is invalid.
((HRESULT)0x8004004CL)
TAPI_E_REGISTRY_SETTING_CORRUPT
The registry setting is corrupt.
((HRESULT)0x8004004DL)
TAPI_E_TERMINAL_PEER
The peer for one of these bridge terminals has already been assigned.
((HRESULT)0x8004004EL)
TAPI_E_PEER_NOT_SET
The peer for this bridge terminal must be set to complete this operation.
((HRESULT)0x8004004FL)
TAPI_E_NOEVENT
There is no event in the MSP's event queue.
((HRESULT)0x80040050L)
TAPI_E_INVALADDRESSTYPE
This address does not support the specified address type.
((HRESULT)0x80040051L)
TAPI_E_RESOURCEUNAVAIL
A resource needed to fulfill the request is not available.
((HRESULT)0x80040052L)
TAPI_E_PHONENOTOPEN
The phone is not open.
TAPI_E_CALLNOTSELECTED
The specified call is not currently selected.
TAPI_E_WRONGEVENT
This information is not available for this type of event.
TAPI_E_NOFORMAT
The format is unknown.
TAPI_E_INVALIDSTREAMSTATE
The operation is not permitted in current stream state.
TAPI_E_WRONG_STATE
The operation requested is not permitted for the current state.
TAPI_E_NOT_INITIALIZED
The object has not been initialized.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3err.h.


TAPI_DIGITMODE_ Constants

The digit mode describes the type, such as DTMF (Dial Tone Multifrequency). The values used are those from the TAPI 2 LINEDIGITMODE_ Constants.

See Also

ITDigitDetectionEvent::get_DigitMode, ITLegacyCallMediaControl::DetectDigits, ITLegacyCallMediaControl::GenerateDigits


TAPIMEDIATYPE_ Constants

The following media types are defined:

TAPIMEDIATYPE_AUDIO
0x8
An audio media stream that is entering or leaving the computer. An entering media stream would typically be played on speakers, or sent to a handset device and a leaving stream would typically be captured through a microphone or handset device.
TAPIMEDIATYPE_VIDEO
0x8000
A video media stream that is entering or leaving the computer. An entering media stream would typically be rendered in a video window and a leaving media stream would typically be captured with a video camera.
TAPIMEDIATYPE_DATAMODEM
0x10
A data media stream that is associated with a data modem.
TAPIMEDIATYPE_G3FAX
0x20
A data media stream that is associated with a G3 protocol fax.
TAPIMEDIATYPE_MULTITRACK
A stream is on a multitrack terminal.
MEDIATYPE_RTP_Single_Stream
This GUID is used between an application supplied terminal and the MSP's stream. If the pin of the terminal supports this media type, the stream will exchange raw RTP data with the terminal. This mode is supported only by the video streams on the H323 MSP and IPConf MSP for Windows 2000 SP1 or above.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITQOSEvent::get_MediaType, ITAMMediaFormat::get_MediaFormat, ITAMMediaFormat::put_MediaFormat, ITCallInfo::get_CallInfoLong, ITMediaSupport::get_MediaTypes, ITTerminalSupport::CreateTerminal


TAPIPROTOCOL_ Constants

The following protocols are defined by TAPI 3.0, and the CLSIDs are in Tapi3.lib. Service providers can define additional protocols.

CLSID TAPIPROTOCOL_PSTN
Public switched telephone network protocol.
CLSID TAPIPROTOCOL_H323
H323 protocol.
CLSID TAPIPROTOCOL_Multicast
Multicast protocol.

BSTR versions of the protocol constants are declared for the use of Visual Basic applications.

BSTR TAPIPROTOCOL_String_PSTN
BSTR TAPIPROTOCOL_String_H323
BSTR TAPIPROTOCOL_String_Multicast


Terminal Class

The terminal class GUIDs identify a particular terminal by capabilities.

CLSID_HandsetTerminal
Telephone handset.
CLSID_HeadsetTerminal
Head set.
CLSID_MediaStreamTerminal
Media stream terminal, dynamically created.
CLSID_MicrophoneTerminal
Microphone.
CLSID_SpeakerphoneTerminal
Speaker phone.
CLSID_SpeakersTerminal
Speakers.
CLSID_VideoInputTerminal
Video input terminal.
CLSID_VideoWindowTerm
Video display window, dynamically created.

The BSTR version of the terminal classes is mainly designated for the use of Visual Basic applications. (For example, they are returned as the elements of the collection obtained with get_DynamicTerminalClasses.)

BSTR CLSID_String_HandsetTerminal
BSTR CLSID_String_HeadsetTerminal
BSTR CLSID_String_MediaStreamTerminal
BSTR CLSID_String_MicrophoneTerminal
BSTR CLSID_String_SpeakerphoneTerminal
BSTR CLSID_String_SpeakersTerminal
BSTR CLSID_String_VideoInputTerminal
BSTR CLSID_String_VideoWindowTerm

See Also

ITTerminalSupport::CreateTerminal, ITTerminal::get_TerminalClass, ITTerminalManager::CreateDynamicTerminal, ITTerminalManager::GetDynamicTerminalClasses, ITTerminalSupport::EnumerateDynamicTerminalClasses


Call and Media Control Enumerations

TAPI 3.0 methods use the following enumerations to set and report on events and states.

ADDRESS_CAPABILITY

ADDRESS_CAPABILITY_STRING

ADDRESS_EVENT

ADDRESS_STATE

CALLHUB_EVENT

CALLHUB_STATE

CALLINFOCHANGE_CAUSE

CALLINFO_BUFFER

CALLINFO_LONG

CALLINFO_STRING

CALL_MEDIA_EVENT_CAUSE

CALL_MEDIA_EVENT

CALL_NOTIFICATION_EVENT

CALL_PRIVILEGE

CALL_STATE

CALL_STATE_EVENT_CAUSE

DISCONNECT_CODE

FINISH_MODE

FT_STATE_EVENT_CAUSE

FULLDUPLEX_SUPPORT

H245_CAPABILITY

MULTICAST_LOOPBACK_MODE

PARTICIPANT_EVENT

PARTICIPANT_TYPED_INFO

PHONE_BUTTON_FUNCTION

PHONE_BUTTON_MODE

PHONE_BUTTON_STATE

PHONE_EVENT

PHONE_HOOK_SWITCH_DEVICE

PHONE_HOOK_SWITCH_STATE

PHONE_LAMP_MODE

PHONE_PRIVILEGE

PHONE_TONE

PHONECAPS_BUFFER

PHONECAPS_LONG

PHONECAPS_STRING

QOS_EVENT

QOS_SERVICE_LEVEL

TAPI_EVENT

TAPI_GATHERTERM

TAPIOBJECT_EVENT

TAPI_OBJECT_TYPE

TAPI_TONEMODE

TERMINAL_DIRECTION

TERMINAL_MEDIA_STATE

TERMINAL_STATE

TERMINAL_TYPE

TMGR_DIRECTION


ADDRESS_CAPABILITY

A member of the ADDRESS_CAPABILITY enum is used by the ITAddressCapabilities::get_AddressCapability method to indicate the address capability required.

typedef enum ADDRESS_CAPABILITY
{
  AC_ADDRESSTYPES,
  AC_BEARERMODES,
  AC_MAXACTIVECALLS,
  AC_MAXONHOLDCALLS,
  AC_MAXONHOLDPENDINGCALLS,
  AC_MAXNUMCONFERENCE,
  AC_MAXNUMTRANSCONF,
  AC_MONITORDIGITSUPPORT,
  AC_GENERATEDIGITSUPPORT,
  AC_GENERATETONEMODES,
  AC_GENERATETONEMAXNUMFREQ,
  AC_MONITORTONEMAXNUMFREQ,
  AC_MONITORTONEMAXNUMENTRIES,
  AC_DEVCAPFLAGS,
  AC_ANSWERMODES,
  AC_LINEFEATURES,
  AC_SETTABLEDEVSTATUS,
  AC_PARKSUPPORT,
  AC_CALLERIDSUPPORT,
  AC_CALLEDIDSUPPORT,
  AC_CONNECTEDIDSUPPORT,
  AC_REDIRECTIONIDSUPPORT,
  AC_REDIRECTINGIDSUPPORT,
  AC_ADDRESSCAPFLAGS,
  AC_CALLFEATURES1,
  AC_CALLFEATURES2,
  AC_REMOVEFROMCONFCAPS,
  AC_REMOVEFROMCONFSTATE,
  AC_TRANSFERMODES,
  AC_ADDRESSFEATURES,
  AC_PREDICTIVEAUTOTRANSFERSTATES,
  AC_MAXCALLDATASIZE,
  AC_LINEID,
  AC_ADDRESSID,
  AC_FORWARDMODES,
  AC_MAXFORWARDENTRIES,
  AC_MAXSPECIFICENTRIES,
  AC_MINFWDNUMRINGS,
  AC_MAXFWDNUMRINGS,
  AC_MAXCALLCOMPLETIONS,
  AC_CALLCOMPLETIONCONDITIONS,
  AC_CALLCOMPLETIONMODES,
  AC_PERMANENTDEVICEID
} ADDRESS_CAPABILITY;

Members

AC_ADDRESSCAPFLAGS
The address capability flags describe various Boolean address capabilities. For example, LINEADDRCAPFLAGS_FWDNUMRINGS indicates whether the number of rings for a no-answer can be specified when forwarding on a no-answer.
AC_ADDRESSFEATURES
The line address features describe operations that can be invoked on an address. For example, if LINEADDRFEATURE_FORWARD is set, the address can be forwarded.
AC_ADDRESSID
Address identifier. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
AC_ADDRESSTYPES
An address may support more than one address type, but please note that one may be used during ITAddress::CreateCall.
AC_ANSWERMODES
Answer modes.
AC_BEARERMODES
Bearer modes.
AC_CALLCOMPLETIONCONDITIONS
Call completion conditions.
AC_CALLCOMPLETIONMODES
Call completion modes.
AC_CALLEDIDSUPPORT
Identifies support for called number identification using the LINECALLPARTYID_ flags.
AC_CALLERIDSUPPORT
Identifies support for caller number identification using the LINECALLPARTYID_ flags.
AC_CALLFEATURES1
Call feature set one.
AC_CALLFEATURES2
Supplemental call features for conferencing, transferring, and parking calls.
AC_CONNECTEDIDSUPPORT
Indicates whether connected ID is supported using the LINECALLPARTYID_ flags.
AC_DEVCAPFLAGS
Device capability flags.
AC_FORWARDMODES
Forwarding modes.
AC_GENERATEDIGITSUPPORT
Specifies digit modes that can be generated on this address using a subset of the LINEDIGITMODE_ flags: LINEDIGITMODE_PULSE indicates digits can be generated as pulse/rotary tones, and LINEDIGITMODE_DTMF indicates digits can be generated as DTMF tones. If no flag is set, digit generation is not supported.
AC_GENERATETONEMAXNUMFREQ
Contains the maximum number of frequencies that can be specified in describing a general tone.
AC_GENERATETONEMODES
Specifies the different kinds of tones that can be generated on this line, of type LINETONEMODE_.
AC_LINEFEATURES
Specifies the features available for this line using the LINEFEATURE_ constants. Invoking a supported feature requires the line to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This member allows an application to discover which line features can be (and which can never be) supported by the device.
AC_LINEID
Returns the device identifier of the line device with which this address is associated. TAPI 2.1 cross-reference: LINEADDRESSCAPS.
AC_MAXACTIVECALLS
The maximum number of (minimum bandwidth) calls that can be active (connected) on the line at any one time. The actual number of active calls can be lower if higher bandwidth calls are established on the line.
AC_MAXCALLCOMPLETIONS
The maximum number of concurrent call completion requests that can be outstanding on this address. Zero implies that call completion is not available.
AC_MAXCALLDATASIZE
Maximum data block size allowed.
AC_MAXFORWARDENTRIES
The maximum number of different forwarding entries that can be supported by the current address.
AC_MAXFWDNUMRINGS
Specifies the maximum number of rings that can be set to determine when a call is officially considered "no answer."
AC_MAXNUMCONFERENCE
Contains the maximum number of parties that can join a single conference call on this address.
AC_MAXNUMTRANSCONF
Specifies the number of parties (including "self") that can be added in a conference call that is initiated as a generic consultation call using ITBasicCallControl::Transfer and ITBasicCallControl::Finish (FM_ASCONFERENCE).
AC_MAXONHOLDCALLS
Maximum number of calls that can be on hold at once.
AC_MAXONHOLDPENDINGCALLS
Maximum number of calls that can be simultaneously pending transfer or conference.
AC_MAXSPECIFICENTRIES
Specifies the maximum number of entries that can be set using ITForwardInformation::SetForwardType that can contain forwarding instructions based on a specific caller (selective call forwarding). This member is zero if selective call forwarding is not supported.
AC_MINFWDNUMRINGS
Specifies the minimum number of rings that can be set to determine when a call is officially considered "no answer."
AC_MONITORDIGITSUPPORT
Specifies digit modes detectable on this address using the LINEDIGITMODE_ flags. If no flag is set, digit monitoring is not supported.
AC_MONITORTONEMAXNUMENTRIES
Contains the maximum number of entries that can be specified in a tone list.
AC_MONITORTONEMAXNUMFREQ
Contains the maximum number of frequencies that can be specified when monitoring a general tone. A value of 0 indicates that tone monitor is not available.
AC_PARKSUPPORT
Indicates whether park is supported using the LINEPARKMODE_ flags.
AC_PERMANENTDEVICEID
The permanent identifier by which the line device is known in the system's configuration. This value does not change as lines are added and removed from the system. It can therefore be used to link line-specific information in the registry or other files in a way that is not affected by changes in other lines. If a line has more than one address, all addresses will have the same permanent device identifier. TSP writers should note that this value must be preserved across OS upgrades.
AC_PREDICTIVEAUTOTRANSFERSTATES
The call state or states upon which a call made by a predictive dialer can be set to automatically transfer the call to another address; one or more of the LINECALLSTATE_ constants. The value 0 indicates automatic transfer based on call state is unavailable.
AC_REDIRECTINGIDSUPPORT
Indicates whether redirecting ID is supported using the LINECALLPARTYID_ flags.
AC_REDIRECTIONIDSUPPORT
Indicates whether redirection ID is supported using the LINECALLPARTYID_ flags.
AC_REMOVEFROMCONFCAPS
Specifies the address's capabilities for removing calls from a conference call. This member uses the LINEREMOVEFROMCONF_ constants.
AC_REMOVEFROMCONFSTATE
Uses the LINECALLSTATE_ constants to specify the state of the call after it has been removed from a conference call.
AC_SETTABLEDEVSTATUS
Indicates LINEDEVSTATUS_ values that can be modified.
AC_TRANSFERMODES
Transfer modes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAddressCapabilities::get_AddressCapability, ITAddress, Address object


ADDRESS_CAPABILITY_STRING

The ADDRESS_CAPABILITY_STRING enum is used to check on address capabilities which are described by strings.

typedef enum ADDRESS_CAPABILITY_STRING
{
  ACS_PROTOCOL,
  ACS_ADDRESSDEVICESPECIFIC,
  ACS_LINEDEVICESPECIFIC,
  ACS_PROVIDERSPECIFIC,
  ACS_SWITCHSPECIFIC,
  ACS_PERMANENTDEVICEGUID
} ADDRESS_CAPABILITY_STRING;

Members

ACS_ADDRESSDEVICESPECIFIC
Describes an address device-specific capability. The value is TSP dependent and can be a structure, a string, or some other type. An application should use the BSTR pointer received from Tapi3.dll as a pointer to an array of bytes (a buffer), and then interpret the buffer according to TSP specifications. Corresponds to the dwDevSpecific and dwDevSpecificSize members of TAPI 2's LINEADDRESSCAPS structure.
ACS_LINEDEVICESPECIFIC
Describes a line device-specific capability. The value is TSP dependent and can be a structure, a string, or some other type. An application should use the BSTR pointer received from Tapi3.dll as a pointer to an array of bytes (a buffer), and then interpret the buffer according to TSP specifications. Corresponds to the dwDevSpecific and dwDevSpecificSize members of TAPI 2's LINEDEVCAPS structure.
ACS_PROTOCOL
Describes a protocol-specific capability. The value is returned as a GUID in string format. For possible values, see TAPIPROTOCOL_. A TSP may define additional values. Corresponds to the ProtocolGuid member of TAPI 2's LINEDEVCAPS structure.
ACS_PROVIDERSPECIFIC
Describes a provider-specific capability. The value is a plain string. It can be used with regular BSTR functions for operations such as printing and concatenating. A specific TSP might included embedded NULL characters inside these strings. If so, an application should take care when printing the value. If the embedded NULL characters are not replaced with blanks, the strings will appear truncated when printed. Corresponds to the dwProviderInfoSize and dwProviderInfoOffset members of TAPI 2's LINEDEVCAPS structure.
ACS_SWITCHSPECIFIC
Describes a switch-specific capability. The value is a plain string. It can be used with regular BSTR functions for operations such as printing and concatenating. A specific TSP might included embedded NULL characters inside these strings. If so, an application should take care when printing the value. If the embedded NULL characters are not replaced with blanks, the strings will appear truncated when printed. Corresponds to the dwSwitchInfoSize and dwSwitchInfoOffset members of TAPI 2's LINEDEVCAPS structure.
ACS_PERMANENTDEVICEGUID
Describes the GUID of a permanent device. The value is returned as a GUID in string format. This identifier must remain stable throughout, including operating system upgrades. Corresponds to the PermanentLineGuid member of TAPI 2's LINEDEVCAPS structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAddressCapabilities::get_AddressCapabilityString, ITAddress, Address object, LINEADDRESSCAPS, LINEDEVCAPS, TAPIPROTOCOL_


ADDRESS_EVENT

The ADDRESS_EVENT enum describes address events. The ITAddressEvent::get_Event method returns a member of this enum to indicate the type of address event that occurred.

typedef enum ADDRESS_EVENT
{
  AE_STATE,
  AE_CAPSCHANGE,
  AE_RINGING,
  AE_CONFIGCHANGE,
  AE_FORWARD,
  AE_NEWTERMINAL,
  AE_REMOVETERMINAL
} ADDRESS_EVENT;

Members

AE_STATE
The address state has changed. See ITAddress::get_State.
AE_CAPSCHANGE
Address capabilities have changed. See capability flags.
AE_RINGING
There is ringing on the address.
AE_CONFIGCHANGE
The address configuration has changed.
AE_FORWARD
Forwarding has changed. See ITAddress::get_CurrentForwardInfo.
AE_NEWTERMINAL
A new terminal has been added.
AE_REMOVETERMINAL
A terminal has been removed.

Remarks

Certain events on PnP devices will not be received until after the first time static terminals are enumerated using ITTerminalSupport::EnumerateStaticTerminals or ITTerminalSupport::get_StaticTerminals.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAddressEvent::get_Event, ITCallNotificationEvent, Event Notification overview


ADDRESS_STATE

The ADDRESS_STATE enum is used by the ITAddress::get_State method to check the address state.

typedef enum ADDRESS_STATE
{
  AS_INSERVICE,
  AS_OUTOFSERVICE
} ADDRESS_STATE;

Members

AS_INSERVICE
Normal state; the address can be used.
AS_OUTOFSERVICE
The address is temporarily out of service, but may go back into service at some time.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAddress::get_State, ITAddress, Address object


CALLHUB_EVENT

The CALLHUB_EVENT enum describes CallHub events. The ITCallHubEvent::get_Event method returns a member of this enum to indicate the type of CallHub event that occurred.

typedef enum CALLHUB_EVENT
{
  CHE_CALLJOIN,
  CHE_CALLLEAVE,
  CHE_CALLHUBNEW,
  CHE_CALLHUBIDLE
} CALLHUB_EVENT;

Members

CHE_CALLJOIN
A new call has joined the CallHub.
CHE_CALLLEAVE
A call has left the CallHub.
CHE_CALLHUBNEW
A new CallHub has appeared.
CHE_CALLHUBIDLE
A CallHub has gone idle.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallHubEvent::get_Event


CALLHUB_STATE

The CALLHUB_STATE enum is a state indicator returned by the ITCallHub::get_State method.

typedef enum CALLHUB_STATE
{
  CHS_ACTIVE,
  CHS_IDLE
} CALLHUB_STATE;

Members

CHS_ACTIVE
The CallHub is active. There is at least one call that is not in the CS_DISCONNECTED state.
CHS_IDLE
All calls associated with this CallHub are in the CS_DISCONNECTED state.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallHub::get_State


CALLINFOCHANGE_CAUSE

The CALLINFOCHANGE_CAUSE enum is used by the ITCallInfoChangeEvent::get_Cause method to return a description of the type of call information that has changed.

You can retrieve specific information about the change by using the TAPI 3 ITCallInfo interface. TAPI 2 applications use lineGetCallInfo or lineGetCallStatus.

typedef enum CALLINFOCHANGE_CAUSE
{
  CIC_OTHER,
  CIC_DEVSPECIFIC,
  CIC_BEARERMODE,
  CIC_RATE,
  CIC_APPSPECIFIC,
  CIC_CALLID,
  CIC_RELATEDCALLID,
  CIC_ORIGIN,
  CIC_REASON,
  CIC_COMPLETIONID,
  CIC_NUMOWNERINCR,
  CIC_NUMOWNERDECR,
  CIC_NUMMONITORS,
  CIC_TRUNK,
  CIC_CALLERID,
  CIC_CALLEDID,
  CIC_CONNECTEDID,
  CIC_REDIRECTIONID,
  CIC_REDIRECTINGID,
  CIC_USERUSERINFO,
  CIC_HIGHLEVELCOMP,
  CIC_LOWLEVELCOMP,
  CIC_CHARGINGINFO,
  CIC_TREATMENT,
  CIC_CALLDATA,
  CIC_PRIVILEGE,
  CIC_MEDIATYPE
} CALLINFOCHANGE_CAUSE;

Members

CIC_OTHER
Unspecified call information has changed.
CIC_DEVSPECIFIC
Call information specific to a device has changed.
CIC_BEARERMODE
The bearer mode for the call has changed.
CIC_RATE
The rate has changed.
CIC_APPSPECIFIC
Call information specific to an application has changed. Application-specific information is used to pass information between applications in a multi-application environment. The information is not interpreted by the API implementation or the service provider. Only applications with owner privileges for the call can set it
CIC_CALLID
The call identifier has changed.
CIC_RELATEDCALLID
The related call identifier has changed.
CIC_ORIGIN
The call origin has changed.
CIC_REASON
The call reason has changed.
CIC_COMPLETIONID
The completion identifier has changed.
CIC_NUMOWNERINCR
The number of owners has increased.
CIC_NUMOWNERDECR
The number of owners has decreased.
CIC_NUMMONITORS
The number of call monitors has changed.
CIC_TRUNK
Trunk used on call has changed.
CIC_CALLERID
The caller identifier has changed.
CIC_CALLEDID
The called identifier has changed.
CIC_CONNECTEDID
The connected identifier has changed.
CIC_REDIRECTIONID
The redirection identifier has changed.
CIC_REDIRECTINGID
The redirecting identifier has changed.
CIC_USERUSERINFO
The user-user information buffer has changed.
CIC_HIGHLEVELCOMP
The high-level compatibility information has changed (ISDN Q.931).
CIC_LOWLEVELCOMP
The low-level compatibility information has changed (ISDN Q.931).
CIC_CHARGINGINFO
The call's charging information has changed.
CIC_TREATMENT
Treatment of calls on hold has changed.
CIC_CALLDATA
The call data buffer has changed.
CIC_PRIVILEGE
Call privilege has changed.
CIC_MEDIATYPE
The call media type has changed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallInfoChangeEvent::get_Cause


CALLINFO_BUFFER

The CALLINFO_BUFFER enum indicates the type of buffer accessed by the ITCallInfo::GetCallInfoBuffer method or the ITCallInfo::SetCallInfoBuffer method.

The ITCallInfo::get_CallInfoBuffer and ITCallInfo::put_CallInfoBuffer methods are provided for Automation client applications, such as those written in Visual Basic.

typedef enum CALLINFO_BUFFER
{
  CIB_USERUSERINFO,
  CIB_DEVSPECIFICBUFFER,
  CIB_CALLDATABUFFER,
  CIB_CHARGINGINFOBUFFER,
  CIB_HIGHLEVELCOMPATIBILITYBUFFER,
  CIB_LOWLEVELCOMPATIBILITYBUFFER,
} CALLINFO_BUFFER;

Members

CIB_USERUSERINFO
The user-user information buffer allows an application to send information to the remote party on a call or receive information from that party.
CIB_DEVSPECIFICBUFFER
The device-specific buffer allows an application to communicate with a TSP concerning device-specific capabilities. The precise nature of these capabilities depends on the implementation of the service provider.
CIB_CALLDATABUFFER
The call data buffer allows an application to communicate with a TSP concerning a specific call. The precise nature of this information depends on the implementation of the service provider.
CIB_CHARGINGINFOBUFFER
The charging information buffer's format is specified by other standards (ISDN Q.931).
CIB_HIGHLEVELCOMPATIBILITYBUFFER
The high-level compatibility buffer's format is specified by other standards (ISDN Q.931).
CIB_LOWLEVELCOMPATIBILITYBUFFER
The low-level compatibility buffer's format is specified by other standards (ISDN Q.931).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallInfo::GetCallInfoBuffer, ITCallInfo::SetCallInfoBuffer, ITCallInfo::get_CallInfoBuffer, ITCallInfo::put_CallInfoBuffer


CALLINFO_LONG

The CALLINFO_LONG enum is used by ITCallInfo methods that set and get call information of type LONG.

typedef enum CALLINFO_LONG
{
  CIL_MEDIATYPESAVAILABLE,
  CIL_BEARERMODE,
  CIL_CALLERIDADDRESSTYPE,
  CIL_CALLEDIDADDRESSTYPE,
  CIL_CONNECTEDIDADDRESSTYPE,
  CIL_REDIRECTIONIDADDRESSTYPE,
  CIL_REDIRECTINGIDADDRESSTYPE,
  CIL_ORIGIN,
  CIL_REASON,
  CIL_APPSPECIFIC,
  CIL_CALLPARAMSFLAGS,
  CIL_CALLTREATMENT,
  CIL_MINRATE,
  CIL_MAXRATE,
  CIL_COUNTRYCODE,
  CIL_CALLID,
  CIL_RELATEDCALLID,
  CIL_COMPLETIONID,
  CIL_NUMBEROFOWNERS,
  CIL_NUMBEROFMONITORS,
  CIL_TRUNK,
  CIL_RATE,
} CALLINFO_LONG;

Members

CIL_MEDIATYPESAVAILABLE
The media types available on the call.
CIL_BEARERMODE
The bearer mode of a call is described by the LINEBEARERMODE_ Constants.
CIL_CALLERIDADDRESSTYPE
The address type of the caller.
CIL_CALLEDIDADDRESSTYPE
The address type of the called party.
CIL_CONNECTEDIDADDRESSTYPE
The address type of the connected party.
CIL_REDIRECTIONIDADDRESSTYPE
The address type of the destination to which a call has been redirected.
CIL_REDIRECTINGIDADDRESSTYPE
The address type of the location that redirected the call.
CIL_ORIGIN
The origin of a call is described by the LINECALLORIGIN_ Constants, such as LINECALLORIGIN_EXTERNAL.
CIL_REASON
The reason for a call is described by the LINECALLREASON_ Constants, such as LINECALLREASON_FWDUNCOND.
CIL_APPSPECIFIC
Application-specific information is used to pass information between applications in a multi-application environment. The information is not interpreted by the API implementation or the service provider. Only applications with owner privileges for the call can set it.
CIL_CALLPARAMSFLAGS
Call parameter flags are described by LINECALLPARAMFLAGS_ Constants, such as LINECALLPARAMFLAGS_BLOCKID. These flags are normally set during the creation of an outgoing call.
CIL_CALLTREATMENT
Call treatment identifies how a call that is on hold or unanswered gets handled, and is described by LINECALLTREATMENT_ Constants, such as LINECALLTREATMENT_MUSIC.
CIL_MINRATE
The minimum rate for a call's data stream in bps (bits per second).
CIL_MAXRATE
The maximum rate for a call's data stream in bps (bits per second).
CIL_COUNTRYCODE
Country code.
CIL_CALLID
Call identifier. Some service providers assign a unique code to each call.
CIL_RELATEDCALLID
Call identifier for a call related to the current call, such as on a conference.
CIL_COMPLETIONID
Completion identifier. The completion identifier is used to identify individual completion requests in progress. A completion identifier becomes invalid and can be reused after the request completion or after an outstanding request is canceled.
CIL_NUMBEROFOWNERS
The number of applications having owner privileges for the current call.
CIL_NUMBEROFMONITORS
The number of applications having monitor privileges for the current call.
CIL_TRUNK
The trunk identifier for the current call.
CIL_RATE
The current rate for a call's data stream in bps (bits per second).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallInfo::get_CallInfoLong, ITCallInfo::put_CallInfoLong


CALLINFO_STRING

The CALLINFO_STRING enum is used by ITCallInfo methods that set and get call information involving the use of strings.

typedef enum CALLINFO_STRING
{
  CIS_CALLERIDNAME,
  CIS_CALLERIDNUMBER,
  CIS_CALLEDIDNAME,
  CIS_CALLEDIDNUMBER,
  CIS_CONNECTEDIDNAME,
  CIS_CONNECTEDIDNUMBER,
  CIS_REDIRECTIONIDNAME,
  CIS_REDIRECTIONIDNUMBER,
  CIS_REDIRECTINGIDNAME,
  CIS_REDIRECTINGIDNUMBER,
  CIS_CALLEDPARTYFRIENDLYNAME,
  CIS_COMMENT,
  CIS_DISPLAYABLEADDRESS,
  CIS_CALLINGPARTYID,
} CALLINFO_STRING;

Members

CIS_CALLERIDNAME
The name of the caller.
CIS_CALLERIDNUMBER
The number of the caller.
CIS_CALLEDIDNAME
The name of the called location.
CIS_CALLEDIDNUMBER
The number of the called location.
CIS_CONNECTEDIDNAME
The name of the connected location.
CIS_CONNECTEDIDNUMBER
The number of the connected location.
CIS_REDIRECTIONIDNAME
The name of the location to which a call has been redirected.
CIS_REDIRECTIONIDNUMBER
The number of the location to which a call has been redirected.
CIS_REDIRECTINGIDNAME
The name of the location that redirected the call.
CIS_REDIRECTINGIDNUMBER
The number of the location that redirected the call.
CIS_CALLEDPARTYFRIENDLYNAME
The called party friendly name.
CIS_COMMENT
A comment about the call provided by the application that originated the call.
CIS_DISPLAYABLEADDRESS
A displayable version of the called or calling address.
CIS_CALLINGPARTYID
The identifier of the calling party.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallInfo::get_CallInfoString, ITCallInfo::put_CallInfoString


CALL_MEDIA_EVENT_CAUSE

The CALL_MEDIA_EVENT_CAUSE enum is used by ITCallMediaEvent::get_Cause method to return a description of what caused a media event, such as a device timeout.

typedef enum CALL_MEDIA_EVENT_CAUSE
{
  CMC_UNKNOWN,
  CMC_BAD_DEVICE,
  CMC_CONNECT_FAIL,
  CMC_LOCAL_REQUEST,
  CMC_REMOTE_REQUEST,
  CMC_MEDIA_TIMEOUT,
  CMC_MEDIA_RECOVERED
} CALL_MEDIA_EVENT_CAUSE;

Members

CMC_UNKNOWN
Call media is unknown.
CMC_BAD_DEVICE
Device source or renderer is not functioning.
CMC_CONNECT_FAIL
Could not connect to media device.
CMC_LOCAL_REQUEST
A local request has been received.
CMC_REMOTE_REQUEST
A remote request has been received.
CMC_MEDIA_TIMEOUT
The media device timed out.
CMC_MEDIA_RECOVERED
Media processing has resumed after an interruption.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallMediaEvent::get_Cause


CALL_MEDIA_EVENT

The CALL_MEDIA_EVENT enum describes call media events. The ITCallMediaEvent::get_Event method returns a member of this enum to indicate the type of call media event that occurred.

typedef enum CALL_MEDIA_EVENT
{
  CME_NEW_STREAM,
  CME_STREAM_FAIL,
  CME_TERMINAL_FAIL,
  CME_STREAM_NOT_USED,
  CME_STREAM_ACTIVE,
  CME_STREAM_INACTIVE
} CALL_MEDIA_EVENT;

Members

CME_NEW_STREAM
A new media stream has been created.
CME_STREAM_FAIL
A media stream or stream request has failed.
CME_TERMINAL_FAIL
A terminal has failed.
CME_STREAM_NOT_USED
The media stream has not been used.
CME_STREAM_ACTIVE
The media stream is active.
CME_STREAM_INACTIVE
The media stream is not active.

Remarks

Due to latency, stream events may continue for a few seconds after a stream or related call session has been torn down.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallMediaEvent::get_Event, Media Service Provider Interface (MSPI)


CALL_NOTIFICATION_EVENT

The CALL_NOTIFICATION_EVENT enum describes call notification events. The ITCallNotificationEvent::get_Event method returns a member of this enum to indicate the type of call notification event that occurred.

typedef enum CALL_NOTIFICATION_EVENT
{
  CNE_OWNER,
  CNE_MONITOR

} CALL_NOTIFICATION_EVENT;

Members

CNE_OWNER
The current application owns the call on which the event occurred.
CNE_MONITOR
The current application is monitoring the call on which the event occurred.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallNotificationEvent::get_Event, ITCallNotificationEvent


CALL_PRIVILEGE

A CALL_PRIVILEGE member is returned by the ITCallInfo::get_Privilege method, and indicates when the current application owns or is monitoring the current call.

typedef enum CALL_PRIVILEGE
{
  CP_OWNER,
  CP_MONITOR

} CALL_PRIVILEGE;

Members

CP_OWNER
The application is the owner of the call.
CP_MONITOR
The application is a monitor of the call.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallInfo::get_Privilege


CALL_STATE

The CALL_STATE enum is used by the ITCallInfo::get_CallState and ITCallStateEvent::get_State methods.

typedef enum CALL_STATE
{
  CS_IDLE,
  CS_INPROGRESS,
  CS_CONNECTED,
  CS_DISCONNECTED,
  CS_OFFERING,
  CS_HOLD,
  CS_QUEUED
} CALL_STATE;

Members

CS_IDLE
The call has been created, but Connect has not been called yet. A call can never transition into the idle state.
CS_INPROGRESS
Connect has been called, and the service provider is working on making a connection. This state is valid only on outgoing calls. This message is optional, because a service provider may have a call transition directly to the connected state.
CS_CONNECTED
Call has been connected to the remote end and communication can take place.
CS_DISCONNECTED
Call has been disconnected. There are several causes for disconnection. See the table of valid call state transitions below.
CS_OFFERING
A new call has appeared, and is being offered to an application. If the application has owner privileges on the call, it can either call Answer or Disconnect while the call is in the offering state. Current call privilege can be determined by calling ITCallInfo::get_Privilege.
CS_HOLD
The call is in the hold state.
CS_QUEUED
The call is queued.

Following is a table of all valid call state transitions.

From state | To state
CS_IDLE | INPROGRESS
CS_INPROGRESS | CONNECTED FAILED
CS_CONNECTED | HOLD DISCONNECTED
CS_DISCONNECTED | Nothing – call should be freed
CS_OFFERING | CONNECTED DISCONNECTED
CS_HOLD | CONNECTED DISCONNECTED
CS_QUEUED | CONNECTED DISCONNECTED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallInfo::get_CallState, ITCallStateEvent::get_State


CALL_STATE_EVENT_CAUSE

The CALL_STATE_EVENT_CAUSE enum is returned by the ITCallStateEvent::get_Cause method.

typedef enum CALL_STATE_EVENT_CAUSE
{
  CEC_NONE,
  CEC_DISCONNECT_NORMAL,
  CEC_DISCONNECT_BUSY,
  CEC_DISCONNECT_BADADDRESS,
  CEC_DISCONNECT_NOANSWER,
  CEC_DISCONNECT_CANCELLED,
  CEC_DISCONNECT_REJECTED,
  CEC_DISCONNECT_FAILED
} CALL_STATE_EVENT_CAUSE;

Members

CEC_NONE
No call event has occurred.
CEC_DISCONNECT_NORMAL
The call was disconnected as part of the normal life cycle of the call (that is, the call was over, so it was disconnected).
CEC_DISCONNECT_BUSY
An outgoing call failed to connect because the remote end was busy.
CEC_DISCONNECT_BADADDRESS
An outgoing call failed because the destination address was bad.
CEC_DISCONNECT_NOANSWER
An outgoing call failed because the remote end was not answered.
CEC_DISCONNECT_CANCELLED
An outgoing call failed because the caller disconnected.
CEC_DISCONNECT_REJECTED
The outgoing call was rejected by the remote end.
CEC_DISCONNECT_FAILED
The call failed to connect for some other reason.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallStateEvent::get_Cause


DISCONNECT_CODE

The DISCONNECT_CODE enum is used by the ITBasicCallControl::Disconnect method.

typedef enum DISCONNECT_CODE
{
  DC_NORMAL,
  DC_NOANSWER,
  DC_REJECTED
} DISCONNECT_CODE;

Members

DC_NORMAL
The call is being disconnected as part of the normal cycle of the call.
DC_NOANSWER
The call is being disconnected because it has not been answered. (For example, an application may set a certain amount of time for the user to answer the call. If the user does not answer, the application can call Disconnect with the NOANSWER code.)
DC_REJECTED
The user rejected the offered call.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITBasicCallControl::Disconnect


TERMINAL_MEDIA_STATE

[This is preliminary documentation and subject to change.]

The TERMINAL_MEDIA_STATE enum indicates the state of a file terminal.

typedef enum{
  TMS_IDLE,
  TMS_ACTIVE,
  TMS_PAUSED,
  TMS_LASTITEM,
} TERMINAL_MEDIA_STATE;

Members

TMS_IDLE
The file terminal is idle.
TMS_ACTIVE
The file terminal is active.
TMS_PAUSED
The file terminal is paused.
TMS_LASTITEM
Last item in this enum.

See Also

ITFileTerminalEvent::get_State, ITMediaControl::get_MediaState


FINISH_MODE

The FINISH_MODE enum is used by applications to indicate the type of call finish required. Operations that the TAPI DLL performs vary depending on whether a call transfer is being completed or a call is being added to a conference.

typedef enum FINISH_MODE
{
  FM_ASTRANSFER,
  FM_ASCONFERENCE,
} FINISH_MODE;

Members

FM_ASTRANSFER
A call transfer is being finished.
FM_ASCONFERENCE
A call is being added to a conference call.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITBasicCallControl::Finish


FT_STATE_EVENT_CAUSE

[This is preliminary documentation and subject to change.]

The FT_STATE_EVENT_CAUSE enum indicates the type of file terminal event.

typedef enum{
  FTEC_NORMAL,
  FTEC_END_OF_FILE,
  FTEC_READ_ERROR,
  FTEC_WRITE_ERROR,
  FTEC_MAX_DURATION_REACHED,
  FTEC_STOP_ON_SILENCE_THRESHOLD_TRIGGERED,
  FTEC_PAUSE_ON_SILENCE_THRESHOLD_TRIGGERED,
  FTEC_PAUSE_ON_SILENCE_SIGNAL_DETECTED,
} FT_STATE_EVENT_CAUSE;

Members

FTEC_NORMAL
State change in response to a normal API call.
FTEC_END_OF_FILE
Storage EOF reached on playback.
FTEC_READ_ERROR
Storage read error on playback.
FTEC_WRITE_ERROR
Storage write error on the record.
FTEC_MAX_DURATION_REACHED
Maximum duration threshold has been reached on the record.
FTEC_STOP_ON_SILENCE_THRESHOLD_TRIGGERED
The stop-on-silence threshold has been reached.
FTEC_PAUSE_ON_SILENCE_THRESHOLD_TRIGGERED
The pause-on-silence threshold has been reached.
FTEC_PAUSE_ON_SILENCE_SIGNAL_DETECTED
Woken up from the pause caused by triggering the pause-on-silence threshold because a signal was detected.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITFileTerminalEvent::get_Cause


FULLDUPLEX_SUPPORT

The FULLDUPLEX_SUPPORT enum is used by applications interacting with legacy TSPs to indicate whether a specified terminal supports full duplex operations. This enum is returned by the ITLegacyWaveSupport::IsFullDuplex method.

typedef enum FULLDUPLEX_SUPPORT
{
  FDS_SUPPORTED,
  FDS_NOTSUPPORTED,
  FDS_UNKNOWN,
} FULLDUPLEX_SUPPORT;

Members

FDS_SUPPORTED
Full duplex not supported.
FDS_NOTSUPPORTED
Full duplex supported.
FDS_UNKNOWN
The TSP cannot determine whether the device is full duplex.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITLegacyWaveSupport::IsFullDuplex


H245_CAPABILITY

The H245_CAPABILITY enum describes audio and video format support.

typedef enum{
    HC_G711,
    HC_G723,
    HC_H263QCIF,
    HC_H261QCIF,
} H245_CAPABILITY;

Members

HC_G711
The G.711 audio protocol is supported.
HC_G723
The G.723 audio protocol is supported.
HC_H263QCIF
The H.263 video protocol is supported.
HC_H261QCIF
The H.263 video protocol is supported.

See Also

IH323LineEx::SetDefaultCapabilityPreferrence


MULTICAST_LOOPBACK_MODE

The MULTICAST_LOOPBACK_MODE enum describes the multicast loopback mode.

typedef enum{
    MM_NO_LOOPBACK,
    MM_FULL_LOOPBACK,
    MM_SELECTIVE_LOOPBACK,
} MULTICAST_LOOPBACK_MODE;

Members

MM_NO_LOOPBACK
Multicast loopback is disabled. That means two applications on the same machine joining the same multicast group can get each other's packets.
MM_FULL_LOOPBACK
All the packets sent out are looped back as well. This mode is useful only for testing.
MM_SELECTIVE_LOOPBACK
Selective loopback is enabled. That means enabled multiple applications on one machine can join the same multicast group without confusion. The packets are looped back from the stack and each RTP session is responsible for filtering out unwanted packets.

See Also

IMulticastControl::get_LoopbackMode, IMulticastControl::put_LoopbackMode


PARTICIPANT_EVENT

The PARTICIPANT_EVENT enum describes participant events. The ITParticipantEvent::get_Event method returns a member of this enum to indicate the type of conference participant event that occurred. This enum is used by applications that access the IPConf MSP.

typedef enum PARTICIPANT_EVENT
{
  PE_NEW_PARTICIPANT,
  PE_INFO_CHANGE,
  PE_PARTICIPANT_LEAVE,

  PE_NEW_SUBSTREAM,
  PE_SUBSTREAM_REMOVED,

  PE_SUBSTREAM_MAPPED,
  PE_SUBSTREAM_UNMAPPED,

  PE_PARTICIPANT_TIMEOUT,
  PE_PARTICIPANT_RECOVERED,

  PE_PARTICIPANT_ACTIVE,
  PE_PARTICIPANT_INACTIVE,

  PE_LOCAL_TALKING,
  PE_LOCAL_SILENT
}PARTICIPANT_EVENT;

Members

PE_NEW_PARTICIPANT
A new participant has been added to the conference.
PE_INFO_CHANGE
Information on a participant has changed.
PE_PARTICIPANT_LEAVE
A participant has left the conference.
PE_NEW_SUBSTREAM
A new substream has been added to the participant.
PE_SUBSTREAM_REMOVED
A new substream has been removed from the participant.
PE_SUBSTREAM_MAPPED
A participant has been mapped to a substream.
PE_SUBSTREAM_UNMAPPED
A participant has been unmapped from a substream.
PE_PARTICIPANT_TIMEOUT
A participant has been removed from the conference due to a timeout.
PE_PARTICIPANT_RECOVERED
A removed participant is again visible. Usually, this is a participant who timed out but signals are now being received.
PE_PARTICIPANT_ACTIVE
The participant has become active in the conference.
PE_PARTICIPANT_INACTIVE
The participant has become inactive in the conference.
PE_PARTICIPANT_TALKING
The participant has started to talk.
PE_PARTICIPANT_SILENT
The participant has become silent in the conference.
PE_LOCAL_TALKING
The local participant has started to talk.
PE_LOCAL_SILENT
The local participant has become silent in the conference.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.

See Also

ITParticipantEvent::get_Event, IPConf MSP, IPConf MSP Interfaces


PARTICIPANT_TYPED_INFO

The members of the PARTICIPANT_TYPED_INFO enum identify the type of participant information being retrieved by the ITParticipant::get_ParticipantTypedInfo method. This enum is used by applications that access the IPConf MSP.

typedef enum PARTICIPANT_TYPED_INFO
{
  PTI_CANONICALNAME,
  PTI_NAME,
  PTI_EMAILADDRESS,
  PTI_PHONENUMBER,
  PTI_LOCATION,
  PTI_TOOL,
  PTI_NOTES,
  PTI_PRIVATE
}PARTICIPANT_TYPED_INFO;

Members

PTI_CANONICALNAME
Canonical name of participant, such as someone@microsoft.com.
PTI_NAME
Displayable name of participant.
PTI_EMAILADDRESS
Participant's email address.
PTI_PHONENUMBER
Participant's phone address.
PTI_LOCATION
Participant's geographical address.
PTI_TOOL
Participant's application.
PTI_NOTES
Notes concerning participant.
PTI_PRIVATE
Defines an experimental or application-specific Source Description (SDES) extension. See RFC 1889 for details.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.

See Also

ITParticipant::get_ParticipantTypedInfo, IPConf MSP, IPConf MSP Interfaces


PHONE_BUTTON_FUNCTION

[This is preliminary documentation and subject to change.]

The PHONE_BUTTON_FUNCTION enum provides detailed information on a button's function.

typedef enum{
  PBF_UNKNOWN,
  PBF_CONFERENCE,
  PBF_TRANSFER,
  PBF_DROP,
  PBF_HOLD,
  PBF_RECALL,
  PBF_DISCONNECT,
  PBF_CONNECT,
  PBF_MSGWAITON,
  PBF_MSGWAITOFF,
  PBF_SELECTRING,
  PBF_ABBREVDIAL,
  PBF_FORWARD,
  PBF_PICKUP,
  PBF_RINGAGAIN,
  PBF_PARK,
  PBF_REJECT,
  PBF_REDIRECT,
  PBF_MUTE,
  PBF_VOLUMEUP,
  PBF_VOLUMEDOWN,
  PBF_SPEAKERON,
  PBF_SPEAKEROFF,
  PBF_FLASH,
  PBF_DATAON,
  PBF_DATAOFF,
  PBF_DONOTDISTURB,
  PBF_INTERCOM,
  PBF_BRIDGEDAPP,
  PBF_BUSY,
  PBF_CALLAPP,
  PBF_DATETIME,
  PBF_DIRECTORY,
  PBF_COVER,
  PBF_CALLID,
  PBF_LASTNUM,
  PBF_NIGHTSRV,
  PBF_SENDCALLS,
  PBF_MSGINDICATOR,
  PBF_REPDIAL,
  PBF_SETREPDIAL,
  PBF_SYSTEMSPEED,
  PBF_STATIONSPEED,
  PBF_CAMPON,
  PBF_SAVEREPEAT,
  PBF_QUEUECALL,
  PBF_NONE,
  PBF_SEND,
} PHONE_BUTTON_FUNCTION;

Members

PBF_UNKNOWN
A "dummy" function assignment that indicates that the exact function of the button is unknown or has not been assigned.
PBF_CONFERENCE
Initiates a conference call or adds a call to a conference call.
PBF_TRANSFER
Initiates a call transfer or completes the transfer of a call.
PBF_DROP
Drops the active call.
PBF_HOLD
Places the active call on hold.
PBF_RECALL
Takes a call off hold.
PBF_DISCONNECT
Disconnects a call, such as after initiating a transfer.
PBF_CONNECT
Reconnects a call that is on consultation hold.
PBF_MSGWAITON
Turns on a message waiting lamp.
PBF_MSGWAITOFF
Turns off a message waiting lamp.
PBF_SELECTRING
Allows the user to select the ring pattern of the phone.
PBF_ABBREVDIAL
Indicates that the number to be dialed will be a short, abbreviated number consisting of one digit or a few digits.
PBF_FORWARD
Initiates or changes call forwarding to this phone.
PBF_PICKUP
Picks up a call ringing on another phone.
PBF_RINGAGAIN
Initiates a request to be notified if a call cannot be completed normally because of a busy signal or no answer.
PBF_PARK
Parks the active call on another phone, placing it on hold there.
PBF_REJECT
Rejects an incoming call before the call has been answered.
PBF_REDIRECT
Redirects an incoming call to another extension before the call has been answered.
PBF_MUTE
Mutes the phone's microphone device.
PBF_VOLUMEUP
Increases the volume of audio through the phone's handset speaker or speakerphone.
PBF_VOLUMEDOWN
Decreases the volume of audio through the phone's handset speaker or speakerphone.
PBF_SPEAKERON
Turns the phone's external speaker on.
PBF_SPEAKEROFF
Turns the phone's external speaker off.
PBF_FLASH
Generates the equivalent of an onhook/offhook sequence. A flash typically indicates that any digits typed next are to be understood as commands to the switch. On many switches, places an active call on consultation hold.
PBF_DATAON
Indicates that the next call is a data call.
PBF_DATAOFF
Indicates that the next call is not a data call.
PBF_DONOTDISTURB
Places the phone in "do not disturb" mode; incoming calls receive a busy signal or are forwarded to an operator or voicemail system.
PBF_INTERCOM
Connects to the intercom to broadcast a page.
PBF_BRIDGEDAPP
Selects a particular appearance of a bridged address.
PBF_BUSY
Makes the phone appear "busy" to incoming calls.
PBF_CALLAPP
Selects a particular call appearance.
PBF_DATETIME
Causes the phone to display the current date and time; this information would be sent by the switch.
PBF_DIRECTORY
Calls up directory service from the switch.
PBF_COVER
Forwards all calls destined for this phone to another phone used for coverage.
PBF_CALLID
Requests display of the caller ID on the phone's display.
PBF_LASTNUM
Redials the last number dialed.
PBF_NIGHTSRV
Places the phone in the mode it is configured for during night hours.
PBF_SENDCALLS
Sends all calls to another phone used for coverage; same as the PHONEBUTTONFUNCTION_COVER constant.
PBF_MSGINDICATOR
Controls the message indicator lamp.
PBF_REPDIAL
Repertory dialing—the number to be dialed is provided as a shorthand following the pressing of this button.
PBF_SETREPDIAL
Programs the shorthand-to-phone number mappings accessible by means of repertory dialing (the "REPDIAL" button).
PBF_SYSTEMSPEED
The number to be dialed is provided as a shorthand following the pressing of this button. The mappings for system speed dialing are configured inside the switch.
PBF_STATIONSPEED
The number to be dialed is provided as a shorthand following pressing of this button. The mappings for station speed dialing are specific to this station (phone).
PBF_CAMPON
Camps on an extension that returns a busy indication. When the remote station returns to idle, the phone will be rung with a distinctive pattern. Picking up the local phone reinitiates the call.
PBF_SAVEREPEAT
When pressed while a call or call attempt is active, it will remember that call's number or command. When pressed while no call is active (such as during dial tone), it repeats the most recently saved command.
PBF_QUEUECALL
Queues a call to an outside number after it encounters a trunk-busy indication. When a trunk becomes available later, the phone will be rung with a distinctive pattern. Picking up the local phone reinitiates the call.
PBF_NONE
A "dummy" function assignment that indicates that the button does not have a function.
PBF_SEND
Sends a request for a communications session.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_ButtonFunction, ITPhone::put_ButtonFunction


PHONE_BUTTON_MODE

[This is preliminary documentation and subject to change.]

The PHONE_BUTTON_MODE enum describes the mode of a phone button.

typedef enum{
  PBM_DUMMY,
  PBM_CALL,
  PBM_FEATURE,
  PBM_KEYPAD,
  PBM_LOCAL,
  PBM_DISPLAY,
} PHONE_BUTTON_MODE;

Members

PBM_DUMMY
Dummy button.
PBM_CALL
Call button.
PBM_FEATURE
Feature button.
PBM_KEYPAD
Keypad button.
PBM_LOCAL
Local function button, such as mute or volume control.
PBM_DISPLAY
Display button.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_ButtonMode, ITPhone::put_ButtonMode


PHONE_BUTTON_STATE

[This is preliminary documentation and subject to change.]

The PHONE_BUTTON_STATE enum describes the state of a phone button.

typedef enum{
  PBS_UP,
  PBS_DOWN,
  PBS_UNKNOWN,
  PBS_UNAVAIL,
} PHONE_BUTTON_STATE;

Members

PBS_UP
State of the button is up.
PBS_DOWN
State of the button is down.
PBS_UNKNOWN
State of the button is not known.
PBS_UNAVAIL
State of the button is not available.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_ButtonState, ITPhoneEvent::get_ButtonState


PHONE_EVENT

[This is preliminary documentation and subject to change.]

The PHONE_EVENT enum indicates a type of phone event.

typedef enum{
  PE_DISPLAY,
  PE_LAMPMODE,
  PE_RINGMODE,
  PE_RINGVOLUME,
  PE_HOOKSWITCH,
  PE_CAPSCHANGE,
  PE_BUTTON,
  PE_CLOSE,
  PE_NUMBERGATHERED,
  PE_DIALING,
  PE_ANSWER,
  PE_DISCONNECT,
  PE_LASTITEM,
} PHONE_EVENT;

Members

PE_DISPLAY
Phone display has changed.
PE_LAMPMODE
Lamp mode has changed.
PE_RINGMODE
Ringing mode has changed.
PE_RINGVOLUME
Ringing volume has changed.
PE_HOOKSWITCH
Hookswitch status has changed.
PE_CAPSCHANGE
Phone capabilities have changed.
PE_BUTTON
The phone button has changed.
PE_CLOSE
The phone has been closed.
PE_NUMBERGATHERED
A dialed number has been gathered by the phone.
PE_DIALING
The phone is dialing.
PE_ANSWER
The phone has been answered.
PE_DISCONNECT
The phone has been disconnected.
PE_LASTITEM
Last item in enum. Allows device-specific additions to this enum.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhoneEvent::get_Event


PHONE_HOOK_SWITCH_DEVICE

[This is preliminary documentation and subject to change.]

The PHONE_HOOK_SWITCH_DEVICE enum is used to indicate the types of switch hooks on a phone device.

typedef enum{
  PHSD_HANDSET,
  PHSD_SPEAKERPHONE,
  PHSD_HEADSET,
} PHONE_HOOK_SWITCH_DEVICE;

Members

PHSD_HANDSET
The handset's hookswitch.
PHSD_SPEAKERPHONE
The speakerphone's hookswitch.
PHSD_HEADSET
The headset's hookswitch.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_HookSwitchState, ITPhone::put_HookSwitchState, ITPhoneEvent::get_HookSwitchDevice


PHONE_HOOK_SWITCH_STATE

[This is preliminary documentation and subject to change.]

The PHONE_HOOK_SWITCH_STATE enum provides indicators of the phone hookswitch status.

typedef enum{
  PHSS_ONHOOK,
  PHSS_OFFHOOK_MIC_ONLY,
  PHSS_OFFHOOK_SPEAKER_ONLY,
  PHSS_OFFHOOK,
} PHONE_HOOK_SWITCH_STATE;

Members

PHSS_ONHOOK
Indicates that the phone is onhook.
PHSS_OFFHOOK_MIC_ONLY
Indicates that only the phone's microphone is offhook.
PHSS_OFFHOOK_SPEAKER_ONLY
Indicates that only the phone's speaker is offhook.
PHSS_OFFHOOK
Indicates that the phone is offhook.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_HookSwitchState, ITPhone::put_HookSwitchState, ITPhoneEvent::get_HookSwitchState


PHONE_LAMP_MODE

[This is preliminary documentation and subject to change.]

The PHONE_LAMP_MODE enum provides indicators of a phone lamp's status.

typedef enum{
  LM_DUMMY,
  LM_OFF,
  LM_STEADY,
  LM_WINK,
  LM_FLASH,
  LM_FLUTTER,
  LM_BROKENFLUTTER,
  LM_UNKNOWN,
} PHONE_LAMP_MODE;

Members

LM_DUMMY
The lamp identifier has no corresponding lamp.
LM_OFF
The lamp is off.
LM_STEADY
The lamp is on steadily.
LM_WINK
The lamp is winking, which means on and off at a normal rate.
LM_FLASH
The lamp is flashing, which means a slow on and off.
LM_FLUTTER
The lamp is fluttering, which means a fast on and off.
LM_BROKENFLUTTER
The lamp is flashing, which means superposition of a flash and flutter.
LM_UNKNOWN
The lamp mode is not known.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_LampMode, ITPhone::put_LampMode


PHONE_PRIVILEGE

[This is preliminary documentation and subject to change.]

The PHONE_PRIVILEGE enum indicates the application's privilege status with respect to the current phone device.

typedef enum{
  PP_OWNER,
  PP_MONITOR,
} PHONE_PRIVILEGE;

Members

PP_OWNER
The application has owner privileges for the current phone session.
PP_MONITOR
The application has monitor privileges for the current phone session.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::Open, ITPhone::get_Privilege


PHONE_TONE

[This is preliminary documentation and subject to change.]

The PHONE_TONE enum identifies a phone tone.

typedef enum{
  PT_KEYPADZERO,
  PT_KEYPADONE,
  PT_KEYPADTWO,
  PT_KEYPADTHREE,
  PT_KEYPADFOUR,
  PT_KEYPADFIVE,
  PT_KEYPADSIX,
  PT_KEYPADSEVEN,
  PT_KEYPADEIGHT,
  PT_KEYPADNINE,
  PT_KEYPADSTAR,
  PT_KEYPADPOUND,
  PT_KEYPADA,
  PT_KEYPADB,
  PT_KEYPADC,
  PT_KEYPADD,
  PT_NORMALDIALTONE,
  PT_EXTERNALDIALTONE,
  PT_BUSY,
  PT_RINGBACK,
  PT_ERROR,
  PT_SILENCE,
} PHONE_TONE;

Members

PT_KEYPADZERO
Zero.
PT_KEYPADONE
One.
PT_KEYPADTWO
Two.
PT_KEYPADTHREE
Three.
PT_KEYPADFOUR
Four.
PT_KEYPADFIVE
Five.
PT_KEYPADSIX
Six.
PT_KEYPADSEVEN
Seven.
PT_KEYPADEIGHT
Eight.
PT_KEYPADNINE
Nine.
PT_KEYPADSTAR
Star key.
PT_KEYPADPOUND
Pound sign key.
PT_KEYPADA
Supplemental A.
PT_KEYPADB
Supplemental B.
PT_KEYPADC
Supplemental C.
PT_KEYPADD
Supplemental D.
PT_NORMALDIALTONE
Normal dial tone.
PT_EXTERNALDIALTONE
External dial tone.
PT_BUSY
Busy signal tone.
PT_RINGBACK
Ringback tone.
PT_ERROR
Error tone.
PT_SILENCE
No tone.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITAutomatedPhoneControl::StartTone, ITAutomatedPhoneControl::get_Tone


PHONECAPS_BUFFER

[This is preliminary documentation and subject to change.]

The PHONECAPS_BUFFER enum is used by methods that set or get phone capabilities described by a buffer.

typedef enum{
  PCB_DEVSPECIFICBUFFER,
} PHONECAPS_BUFFER;

Members

PCB_DEVSPECIFICBUFFER
Device-specific phone capabilities.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::GetPhoneCapsBuffer, ITPhone::get_PhoneCapsBuffer


PHONECAPS_LONG

[This is preliminary documentation and subject to change.]

The PHONECAPS_LONG enum is used by methods that set or get phone capabilities described by a long value.

typedef enum{
  PCL_HOOKSWITCHES,
  PCL_HANDSETHOOKSWITCHMODES,
  PCL_HEADSETHOOKSWITCHMODES,
  PCL_SPEAKERPHONEHOOKSWITCHMODES,
  PCL_DISPLAYNUMROWS,
  PCL_DISPLAYNUMCOLUMNS,
  PCL_NUMRINGMODES,
  PCL_NUMBUTTONLAMPS,
} PHONECAPS_LONG;

Members

PCL_HOOKSWITCHES
Specifies the hookswitch devices available using one or more members of the PHONE_HOOK_SWITCH_DEVICE enum.
PCL_HANDSETHOOKSWITCHMODES
Specifies the handset hook switch modes.
PCL_HEADSETHOOKSWITCHMODES
Specifies the headset hook switch modes.
PCL_SPEAKERPHONEHOOKSWITCHMODES
Specifies the speakerphone hook switch modes.
PCL_DISPLAYNUMROWS
Specifies the number of rows in a phone display device.
PCL_DISPLAYNUMCOLUMNS
Specifies the number of columns in a phone display device.
PCL_NUMRINGMODES
Specifies the number of ring modes.

If a USB phone returns zero for this value, the phone typically does not have a ringer device. The ringing sound plays on the default audio device for the system; for example, on sound card speakers.

PCL_NUMBUTTONLAMPS
Specifies the number of button lamps.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_PhoneCapsLong


PHONECAPS_STRING

[This is preliminary documentation and subject to change.]

The PHONECAPS_STRING enum is used by methods that set or get phone capabilities described by a string.

typedef enum{
  PCS_PHONENAME,
  PCS_PHONEINFO,
  PCS_PROVIDERINFO,
} PHONECAPS_STRING;

Members

PCS_PHONENAME
Name of the phone.
PCS_PHONEINFO
Phone information string.
PCS_PROVIDERINFO
Phone provider string.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.

See Also

ITPhone::get_PhoneCapsString


QOS_EVENT

The QOS_EVENT enum describes quality of service (QOS) events. The ITQOSEvent::get_Event method returns a member of this enum to indicate the type of QOS event that occurred.

typedef enum QOS_EVENT
{
  QE_NOQOS = 1,
  QE_ADMISSIONFAILURE = 2,
  QE_POLICYFAILURE = 3,
  QE_GENERICERROR = 4
} QOS_EVENT;

Members

QE_NOQOS
QOS is not available.
QE_ADMISSIONFAILURE
The QOS request could not be met.
QE_POLICYFAILURE
The type of QOS requested is not supported.
QE_GENERICERROR
Unspecified QOS error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITQOSEvent, ITQOSEvent::get_Event, ITBasicCallControl::SetQOS, QOS_SERVICE_LEVEL


QOS_SERVICE_LEVEL

The QOS_SERVICE_LEVEL enum is used by the ITBasicCallControl::SetQOS method to indicate quality of service requirements for a call.

typedef enum QOS_SERVICE_LEVEL
{
  QSL_BEST_EFFORT = 3,
  QSL_IF_AVAILABLE = 2,
  QSL_NEEDED = 1
} QOS_SERVICE_LEVEL;

Members

QSL_BEST_EFFORT
Quality of service level desired is "best effort."
QSL_IF_AVAILABLE
Quality of service level desired if available.
QSL_NEEDED
Quality of service level required.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITQOSEvent, ITBasicCallControl::SetQOS


TAPI_EVENT

The TAPI_EVENT enum is used to notify an application that a change has occurred in the TAPI object. The ITTAPIEventNotification::Event method implementation uses members of this enum to indicate the type of object associated with the IDispatch pointer passed by TAPI.

typedef enum TAPI_EVENT
{
  TE_TAPIOBJECT,
  TE_ADDRESS,
  TE_CALLNOTIFICATION,
  TE_CALLSTATE,
  TE_CALLMEDIA,
  TE_CALLHUB,
  TE_CALLINFOCHANGE,
  TE_PRIVATE,
  TE_REQUEST,
  TE_AGENT,
  TE_AGENTSESSION,
  TE_QOSEVENT,
  TE_AGENTHANDLER,
  TE_ACDGROUP,
  TE_QUEUE,
  TE_DIGITEVENT,
  TE_GENERATEEVENT
}TAPI_EVENT;

Members

TE_TAPIOBJECT
Change is in TAPI object itself. See ITTAPIObjectEvent.
TE_ADDRESS
An Address object has changed. See ITAddressEvent.
TE_CALLNOTIFICATION
A new communications session has appeared on the address and the TAPI DLL has created a new call object. This could be a result from an incoming session, a session being handed off by another application, or a session being parked on the address. See ITCallNotificationEvent and ITTAPI::RegisterCallNotifications.
TE_CALLSTATE
The Call state has changed. See ITCallStateEvent.
TE_CALLMEDIA
The media associated with a call has changed. See ITCallMediaEvent.
TE_CALLHUB
A CallHub object has changed. See ITCallHubEvent.
TE_CALLINFOCHANGE
The call information has changed. ITCallInfoChangeEvent.
TE_PRIVATE
A provider-specific private object has changed. The precise type of object referenced is implementation dependent. See Provider-Specific Interfaces for general information and the service provider's documentation for the specific meaning.
TE_REQUEST
A Request object has changed. See ITRequestEvent.
TE_AGENT
An Agent object has changed. See ITAgentEvent.
TE_AGENTSESSION
An AgentSession object has changed. See ITAgentSessionEvent.
TE_QOSEVENT
A QOS event has occurred. See ITQOSEvent.
TE_AGENTHANDLER
An AgentHandler object has changed. See ITAgentHandlerEvent.
TE_ACDGROUP
An ACDGroup object has changed. See ITACDGroupEvent.
TE_QUEUE
A Queue object has changed. See ITQueueEvent.
TE_DIGITEVENT
A digit event has occurred. See ITDigitDetectionEvent.
TE_GENERATEEVENT
A digit generation has occurred. See ITDigitGenerationEvent.

Remarks

You must call the ITTAPI::put_EventFilter method and set the event filter mask to enable reception of events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITTAPIEventNotification::Event, ITACDGroupEvent, ITAddressEvent, ITAgentEvent, ITAgentHandlerEvent, ITAgentSessionEvent, ITCallHubEvent, ITCallInfoChangeEvent, ITCallMediaEvent, ITCallNotificationEvent, ITTAPI::RegisterCallNotifications, ITCallStateEvent, ITQOSEvent, ITQueueEvent, ITRequestEvent, ITTAPIObjectEvent


TAPI_GATHERTERM

[This is preliminary documentation and subject to change.]

TBD.

typedef enum{
  TGT_BUFFERFULL,
  TGT_TERMDIGIT,
  TGT_FIRSTTIMEOUT,
  TGT_INTERTIMEOUT,
  TGT_CANCEL,
} TAPI_GATHERTERM;

Members

TGT_BUFFERFULL
TBD.
TGT_TERMDIGIT
TBD.
TGT_FIRSTTIMEOUT
TBD.
TGT_INTERTIMEOUT
TBD.
TGT_CANCEL
TBD.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.

See Also

ITDigitsGatheredEvent::get_GatherTermination


TAPIOBJECT_EVENT

The TAPIOBJECT_EVENT enum describes TAPI object events. The ITTAPIObjectEvent::get_Event method returns a member of this enum to indicate the type of TAPI object event that occurred.

typedef enum TAPIOBJECT_EVENT
{
  TE_ADDRESSCREATE,
  TE_ADDRESSREMOVE,
  TE_REINIT,
  TE_TRANSLATECHANGE,
  TE_ADDRESSCLOSE
}  TAPIOBJECT_EVENT;

Members

TE_ADDRESSCREATE
A new address has been created.
TE_ADDRESSREMOVE
An address has been moved.
TE_REINIT
The TAPI object has been reinitialized
TE_TRANSLATECHANGE
A translation change has occurred.
TE_ADDRESSCLOSE
Address has been closed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITTAPIObjectEvent::get_Event


TAPI_OBJECT_TYPE

The TAPI_OBJECT_TYPE enum is used to indicate the type of TAPI object involved in an event.

typedef enum TAPI_OBJECT_TYPE
{
  TOT_ADDRESS,
  TOT_CALL,
  TOT_CALLHUB,
  TOT_NONE,
  TOT_TAPI,
  TOT_TERMINAL
}  TAPI_OBJECT_TYPE;

Members

TOT_ADDRESS
Type of TAPI object is Address.
TOT_CALL
Type of TAPI object is Call.
TOT_CALLHUB
Type of TAPI object is CallHub.
TOT_NONE
No TAPI object event has occurred.
TOT_TAPI
Type of TAPI object is TAPI.
TOT_TERMINAL
Type of TAPI object is Terminal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.


TAPI_TONEMODE

[This is preliminary documentation and subject to change.]

TBD.

typedef enum{
  TTM_RINGBACK,
  TTM_BUSY,
  TTM_BEEP,
  TTM_BILLING,
} TAPI_TONEMODE;

Members

TTM_RINGBACK
TBD.
TTM_BUSY
TBD.
TTM_BEEP
TBD.
TTM_BILLING
TBD.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.

See Also

ITLegacyCallMediaControl2::GenerateTone


TERMINAL_DIRECTION

The TERMINAL_DIRECTION enum is used to describe the direction of the media stream with respect to the local machine or the directional capabilities of a terminal.

typedef enum TERMINAL_DIRECTION
{
  TD_CAPTURE,
  TD_RENDER,
  TD_BIDIRECTIONAL
} TERMINAL_DIRECTION;

Members

TD_CAPTURE
The stream is captured on the local machine, and the data is sent out to the remote end of the connection. When applied to a terminal, this means it can originate a stream.
TD_RENDER
The stream is arriving from the remote end of the connection. When applied to a terminal, this means it can render a stream.
TD_BIDIRECTIONAL
The terminal can handle either capture or render streams.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITStream::get_Direction, ITStreamControl::CreateStream, ITTerminal::get_Direction, ITTerminalSupport::CreateTerminal, ITTerminalSupport::GetDefaultStaticTerminal, ITTerminalManager::CreateDynamicTerminal


TERMINAL_STATE

The TERMINAL_STATE enum describes the current state of a terminal device. This enum is returned by the ITTerminal::get_State method.

typedef enum TERMINAL_STATE
{
  TS_INUSE,
  TS_NOTINUSE
} TERMINAL_STATE;

Members

TS_INUSE
The terminal is currently in use.
TS_NOTINUSE
The terminal is not currently in use.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITTerminal::get_State


TERMINAL_TYPE

The TERMINAL_TYPE enum describes the type of the terminal. This enum is returned by the ITTerminal::get_TerminalType method.

typedef enum TERMINAL_TYPE
{
  TT_STATIC,
  TT_DYNAMIC
} TERMINAL_TYPE;

Members

TT_STATIC
A static terminal is a terminal that cannot be created and usually refers to hardware device. TAPI enumerates these terminals.
TT_DYNAMIC
A terminal type that can be created. The application must call ITTerminalSupport::CreateTerminal to use this type of terminal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITTerminal::get_TerminalType


TMGR_DIRECTION

[This is preliminary documentation and subject to change.]

The TMGR_DIRECTION enum is used by the pluggable terminal methods to indicate terminal direction.

typedef enum{
  TMGR_TD_CAPTURE,
  TMGR_TD_RENDER,
  TMGR_TD_BOTH,
} TMGR_DIRECTION;

Members

TMGR_TD_CAPTURE
The terminal can originate a media stream.
TMGR_TD_RENDER
The terminal can render a media stream.
TMGR_TD_BOTH
The terminal can handle both directions of a media stream.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.

See Also

ITPluggableTerminalClassRegistration::get_Direction, ITPluggableTerminalClassRegistration::put_Direction


TAPI 3.0 Call and Media Control COM Interfaces

This section contains an alphabetic listing of the TAPI 3.0 interfaces. For a listing of these interfaces by functionality, see Call and Media Control Quick Reference.


IEnumAddress

The IEnumAddress interface provides COM-standard enumeration methods for the ITAddress interface. The ITTAPI::EnumerateAddresses and ITAgentHandler::EnumerateUsableAddresses methods return a pointer to IEnumAddress.

Methods in Vtable Order

IUnknown Methods

IEnumAddress methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress


IEnumAddress::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumAddress **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumAddress interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAddress, ITAddress


IEnumAddress::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITAddress **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITAddress pointer.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAddress, ITAddress


IEnumAddress::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAddress, ITAddress


IEnumAddress::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAddress, ITAddress


IEnumBstr

The IEnumBstr interface provides COM-standard methods to enumerate BSTR strings. The following methods return a pointer to this interface:

ITAddressCapabilities::EnumerateCallTreatments
ITAddressCapabilities::EnumerateCompletionMessages
ITAddressCapabilities::EnumerateDeviceClasses
IMcastLeaseInfo::EnumerateAddresses

Methods in Vtable Order

IUnknown Methods

IEnumBstr methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumBstr::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumBstr **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumBstr interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentSession


IEnumBstr::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  BSTR *ppStrings,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppStrings
[out] Pointer to the list of BSTR pointers returned.
pceltFetched
[in,out,ptr] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppStrings parameter is not a valid pointer.

Remarks

The application must use SysFreeString to free the memory allocated for the ppStrings parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumBstr::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(
);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumBstr::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumCall

The IEnumCall interface provides COM-standard enumeration methods for the ITCallInfo interface. The ITCallHub::EnumerateCalls and ITAddress::EnumerateCalls methods return a pointer to IEnumCall.

Methods in Vtable Order

IUnknown Methods

IEnumCall methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object


IEnumCall::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumCall **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumCall interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object


IEnumCall::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITCallInfo **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITCallInfo pointer.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object


IEnumCall::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object


IEnumCall::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object


IEnumCallHub

The IEnumCallHub interface provides COM-standard enumeration methods for the ITCallHub interface. The ITTAPI::EnumerateCallHubs method returns a pointer to IEnumCallHub.

Methods in Vtable Order

IUnknown Methods

IEnumCallHub methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

CallHub Object


IEnumCallHub::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumCallHub **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumCallHub interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

CallHub Object


IEnumCallHub::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITCallHub **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITCallHub list of pointers returned.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

CallHub Object


IEnumCallHub::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

CallHub Object


IEnumCallHub::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

CallHub Object


IEnumCallingCard

The IEnumCallingCard interface provides COM-standard enumeration methods for the ITCallingCard interface. The ITAddressTranslation::EnumerateCallingCards method returns a pointer to IEnumCallingCard.

Methods in Vtable Order

IUnknown Methods

IEnumCallingCard methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumCallingCard::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumCallingCard **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumCallingCard interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumCallingCard::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITCallingCard **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITCallingCard pointer.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumCallingCard::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumCallingCard::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumLocation

The IEnumLocation interface provides COM-standard enumeration methods for the ITLocationInfo interface. The ITAddressTranslation::EnumerateLocations method returns a pointer to IEnumLocation.

Methods in Vtable Order

IUnknown Methods

IEnumLocation methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumLocation::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumLocation **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumLocation interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumLocation::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITLocationInfo **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITLocationInfo pointer.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumLocation::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumLocation::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumParticipant

The IEnumParticipant interface provides COM-standard enumeration methods for the ITParticipant interface. The ITParticipantControl::EnumerateParticipants method returns a pointer to IEnumParticipant.

Methods in Vtable Order

IUnknown Methods

IEnumParticipant methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant


IEnumParticipant::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumParticipant **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumParticipant interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

IEnumParticipant, ITParticipant


IEnumParticipant::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITParticipant **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt), size_is(celt)] Pointer to ITAgentHandler interfaces.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

IEnumParticipant, ITParticipant


IEnumParticipant::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

IEnumParticipant, ITParticipant


IEnumParticipant::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

IEnumParticipant, ITParticipant


IEnumPhone

[This is preliminary documentation and subject to change.]

The IEnumPhone interface provides COM-standard enumeration methods for the ITPhone interface. The ITAddress2::EnumeratePhones and ITTAPI2::EnumeratePhones methods return a pointer to IEnumPhone.

Methods in Vtable Order

IUnknown Methods

IEnumPhone methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, ITAddress2::EnumeratePhones, ITTAPI2::EnumeratePhones


IEnumPhone::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumPhone ** ppEnum
);

Parameters

ppEnum
[out,retval] Pointer to new IEnumPhone interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | The method failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPhone


IEnumPhone::Next

[This is preliminary documentation and subject to change.]

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITPhone ** ppElements,
  ULONG * pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out,size_is(celt)] Pointer to ITPhone list of pointers returned.
pceltFetched
[in,out,ptr] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppElements parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPhone, ITPhone


IEnumPhone::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset(
);

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPhone


IEnumPhone::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPhone


IEnumPluggableSuperclassInfo

[This is preliminary documentation and subject to change.]

The IEnumPluggableSuperclassInfo interface provides COM-standard enumeration methods for the ITPluggableTerminalSuperclassInfo interface. The ITTerminalSupport2::EnumeratePluggableSuperclasses method returns a pointer to IEnumPluggableSuperclassInfo.

Methods in Vtable Order

IUnknown Methods

IEnumPluggableSuperclassInfo methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassInfo, ITTerminalSupport2::EnumeratePluggableSuperclasses


IEnumPluggableSuperclassInfo::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumPluggableSuperclassInfo ** ppEnum
);

Parameters

ppEnum
[out,retval] Pointer to new IEnumPluggableSuperclassInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | The method failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableSuperclassInfo


IEnumPluggableSuperclassInfo::Next

[This is preliminary documentation and subject to change.]

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITPluggableTerminalSuperclassInfo ** ppElements,
  ULONG * pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out,size_is(celt)] Pointer to ITPluggableTerminalSuperclassInfo list of pointers returned.
pceltFetched
[in,out,ptr] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppElements parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableSuperclassInfo, ITPluggableTerminalSuperclassInfo


IEnumPluggableSuperclassInfo::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset( );

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableSuperclassInfo


IEnumPluggableSuperclassInfo::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableSuperclassInfo


IEnumPluggableTerminalClassInfo

[This is preliminary documentation and subject to change.]

The IEnumPluggableTerminalClassInfo interface provides COM-standard enumeration methods for the ITPluggableTerminalClassInfo interface. The ITTerminalSupport2::EnumeratePluggableTerminalClasses method returns a pointer to IEnumPluggableTerminalClassInfo.

Methods in Vtable Order

IUnknown Methods

IEnumPluggableTerminalClassInfo methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo, ITTerminalSupport2::EnumeratePluggableTerminalClasses, Terminal Class


IEnumPluggableTerminalClassInfo::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumPluggableTerminalClassInfo ** ppEnum
);

Parameters

ppEnum
[out,retval] Pointer to new IEnumPluggableTerminalClassInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | The method failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableTerminalClassInfo, Terminal Class


IEnumPluggableTerminalClassInfo::Next

[This is preliminary documentation and subject to change.]

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITPluggableTerminalClassInfo ** ppElements,
  ULONG * pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out,size_is(celt)] Pointer to ITPluggableTerminalClassInfo list of pointers returned.
pceltFetched
[in,out,ptr] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppElements parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableTerminalClassInfo, Terminal Class, ITPluggableTerminalClassInfo


IEnumPluggableTerminalClassInfo::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset( );

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableTerminalClassInfo, Terminal Class


IEnumPluggableTerminalClassInfo::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumPluggableTerminalClassInfo, Terminal Class


IEnumTerminal

The IEnumTerminal interface provides COM-standard enumeration methods for the ITTerminal interface. The following methods return a pointer to IEnumTerminal:

ITStream::EnumerateTerminals
ITSubStream::EnumerateTerminals
ITTerminalSupport::EnumerateStaticTerminals

Methods in Vtable Order

IUnknown Methods

IEnumTerminal methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminal::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumTerminal **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumTerminal interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminal::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITTerminal **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITTerminal pointers returned.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminal::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminal::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminalClass

The IEnumTerminalClass interface provides COM-standard enumeration methods to discover and use the dynamic terminal classes that are available. The ITTerminalSupport::EnumerateDynamicTerminalClasses method returns a pointer to this interface.

Methods in Vtable Order

IUnknown Methods

IEnumTerminalClass methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminalClass::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumTerminalClass **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumTerminalClass interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminalClass::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  GUID *pElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
pElements
[out, size_is(celt)] Pointer to list of elements returned.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminalClass::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IEnumTerminalClass::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


IH323LineEx

The IH323LineEx interface is implemented by the H323 MSP and is available only on H.323 address objects. This interface exposes methods that enable creation and manipulation of H323 to SDP bridge terminals.

Note All methods in this interface should be called only after registering for incoming calls on this address.

Methods in Vtable Order

IUnknown Methods

IH323LineEx methods | Description
SetExternalT120Address | Configures an external T.120 address for data exchange.
SetDefaultCapabilityPreferrence | Configures the preference weighting for default capabilities.
SetAlias | Configures a default H.323 alias for the address.

See Also

H323 MSP, H323 to SDP bridge terminals


IH323LineEx::SetExternalT120Address

The SetExternalT120Address method is called by an application to configure an external T.120 address for data exchange. T.120 capability will be advertised during the H.245 negotiation, and the address will be used in the open logic channel acknowledgement so that the other endpoint can set up T.120 sessions with the service listening on that address. If this function is not called, the H.323 service provider will not advertise T.120 capability.

HRESULT SetExternalT120Address(
  IN BOOL fEnable,
  IN DWORD dwIP,
  IN WORD wPort
);

Parameters

fEnable
[in] TRUE to enable T.120 capability; FALSE to disable T.120 capability.
dwIP
[in] DWORD containing the IP address of the external T.120 service.
wPort
[in] WORD containing the port of the external T.120 service.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.


IH323LineEx::SetDefaultCapabilityPreferrence

The SetDefaultCapabilityPreferrence method configures the preference of the default capabilities. Capabilities have a default weight of 100. If the application specifies a higher weight for a capability, it will have a higher priority during the H.245 negotiation. If the application sets the weight of a capability to 0, it will not be used in the H.245 negotiation.

This method is accumulative. For example, if this method is called first to disable a capability and is called again to disable another, both capabilities will be disabled as the result of these two calls.

HRESULT SetDefaultCapabilityPreferrence(
  IN DWORD dwNumCaps,
  IN H245_CAPABILITY * pCapabilities,
  IN DWORD * pWeights
);

Parameters

dwNumCaps
[in] DWORD containing a count of the number of capabilities being set with this method.
pCapabilities
[in] An array of capabilities. Each element of the array is an H245_CAPABILITY value.
pWeights
[in] An array of weights associated with the capabilities.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.


IH323LineEx::SetAlias

The SetAlias method configures a default H.323 alias for the address. This alias will be used in the H.323 call setup exchange so that the other party knows the name of this party.

Calling this method a second time will overwrite the previous alias.

The alias set on this interface will be used only when there is no other way for the TSP to find a proper alias. In the future, when gatekeeper support is added into the TSP, the alias registered to the gatekeeper or assigned by the gatekeeper will override whatever is set through this method.

HRESULT SetAlias(
  IN WCHAR * strAlias,
  IN DWORD dwLength
);

Parameters

strAlias
[in] The alias to be used, in Unicode. Null termination is not required.
dwLength
[in] The length of the alias name, in number of characters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.


IKeyFrameControl

The IKeyFrameControl interface is implemented by the H.323 MSP and is available only on H.323 stream objects. This interface exposes methods that enable creation and manipulation of H323 to SDP bridge terminals. It has two methods that allow the application to ask the remote endpoint to update the video image with a keyframe.

Methods in Vtable Order

IUnknown Methods

IKeyFrameControl methods | Description
UpdatePicture | Asks the video sender to update the picture.
PeriodicUpdatePicture | Configures a timer in the stream that will ask for picture updates periodically.

See Also

H323 MSP, H323 to SDP bridge terminals


IKeyFrameControl::UpdatePicture

The UpdatePicture method is called by an application to ask the video sender to update the picture. Every time this method is called, one request is sent to the video sender. The stream must be active.

HRESULT UpdatePicture(
);

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_INVALIDSTREAMSTATE | The stream is not active.

See Also

H323 MSP, H323 to SDP bridge terminals


IKeyFrameControl::PeriodicUpdatePicture

The PeriodicUpdatePicture method is called by an application to configure a timer in the stream that will ask for picture updates periodically. Picture updates cause high bandwidth usage, so this method will normally be used instead of UpdatePicture.

If the method is called when the stream is active, the timer will start immediately. If the stream is not active, the timer will be started when the stream enters the active state.

HRESULT PeriodicUpdatePicture(
  IN BOOL fEnable,
  IN DWORD dwInterval
);

Parameters

fEnable
[in] TRUE enables the timer. FALSE disables it.
dwInterval
[in] The interval for the timer, in seconds.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Failed for unexpected reasons.

See Also

H323 MSP, H323 to SDP bridge terminals


IMulticastControl

The IMulticastControl interface is implemented by the IPConf MSP and available only on multicast call objects. This interface exposes methods that enable creation and manipulation of H.323 to SDP bridge terminals. The IMulticastControl interface controls the multicast loopback mode.

In the MM_NO_LOOPBACK mode, multicast loopback is disabled, which means two applications on the same machine who join the same multicast group will get each other's packets. This mode has the best performance if there is always only one application joining the multicast group on the machine. MM_NO_LOOPBACK mode is the default mode.

The MM_FULL_LOOPBACK mode is good only for testing. All the packets sent out are looped back as well. This can be used to test if the devices are working.

The MM_SELECTIVE_LOOPBACK mode is used to enable multiple applications on one machine to join the same multicast group. The packets are looped back from the stack, and each RTP session is responsible for filtering out unwanted packets.

Methods in Vtable Order

IMulticastControl methods | Description
get_LoopbackMode | Gets the multicast loopback mode.
put_LoopbackMode | Sets the multicast loopback mode.

See Also

IPConf MSP, H323-SDP Bridge Terminal


IMulticastControl::get_LoopbackMode

The get_LoopbackMode method gets the multicast loopback mode.

HRESULT get_LoopbackMode(
  MULTICAST_LOOPBACK_MODE * pMode
);

Parameters

pMode
[retval][out] Pointer to the MULTICAST_LOOPBACK_MODE descriptor of the current loopback mode.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pMode parameter is not valid.

See Also

IMulticastControl


IMulticastControl::put_LoopbackMode

The put_LoopbackMode sets the multicast loopback mode.

HRESULT put_LoopbackMode(
  MULTICAST_LOOPBACK_MODE mode
);

Parameters

mode
[in] MULTICAST_LOOPBACK_MODE descriptor of the new loopback mode.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The mode parameter is not valid.

See Also

IMulticastControl


ITAddress

The ITAddress interface is the base interface for the Address object. Applications use this interface to get information about and use the Address object.

The ITAddress2 interface derives from the ITAddress interface. ITAddress2 adds methods to the Address object in order to support phone devices.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAddress methods | Description
get_State | Gets the current state of the address.
get_AddressName | Gets the name of the address.
get_ServiceProviderName | Gets the service provider name.
get_TAPIObject | Gets pointer to the TAPI object.
CreateCall | Creates a new Call object that can be used to make an outgoing call.
get_Calls | Creates a collection of calls on the current address. Provided for Automation client applications, such as those written in Visual Basic.
EnumerateCalls | Enumerates calls on the current address.
get_DialableAddress | Gets the BSTR which can be used to connect to this address.
CreateForwardInfoObject | Creates ITForwardInformation, the forwarding information object.
Forward | Forwards calls destined for the address.
get_CurrentForwardInfo | Gets a pointer to the forwarding information object.
put_MessageWaiting | Sets the status of the message waiting on the address.
get_MessageWaiting | Determines if the address has a message waiting.
put_DoNotDisturb | Sets the do not disturb status.
get_DoNotDisturb | Gets the current status of the do not disturb feature on the address.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Address Object, ITAddress2


ITAddress::CreateCall

The CreateCall method creates a new Call object that can be used to make an outgoing call and returns a pointer to the object's ITBasicCallControl interface. The newly created call is in the CS_IDLE state and has no media or terminals selected.

Acceptable input values for call address, address type, and media types are specific to the telephony service provider that supports the current address. For information on TSPs shipped with Windows 2000, see About The Telephony Service Provider (TSP). For third party TSPs, see the documentation provided by the vender.

HRESULT CreateCall(
  BSTR pDestAddress,
  long lAddressType,
  long lMediaTypes,
  ITBasicCallControl **ppCall
);

Parameters

pDestAddress
[in] This BSTR string contains a destination address. The format is provider-specific. This pointer can be NULL for non-dialed addresses (such as with a hot phone) or when all dialing is performed using ITBasicCallControl::Dial. NULL in combination with a NULL pGroupID in ITBasicCallControl::Pickup results in a group pickup. Service providers that have inverse multiplexing capabilities can allow an application to specify multiple addresses at once.
lAddressType
[in] Contains an address type constant, such as LINEADDRESSTYPE_PHONENUMBER, which describes the format of the address. The value must be valid for this address. Use ITAddressCapabilities::get_AddressCapability with AddressCap set to AC_ADDRESSTYPES to verify the value.
lMediaTypes
[in] Identifies the media type or types that will be involved in the call session.
ppCall
[out, retval] Pointer to ITBasicCallControl interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The address type, lAddressType, is invalid or specifies more than one address type.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCall parameter is not a valid pointer.

Remarks

The application must use SysAllocString to allocate memory for the pDestAddress parameter and use SysFreeString to free the memory when the variable is no longer needed.

Calls used as consultation calls, such as during a conference, transfer, or forward operation, must be created using this method.

Note for TAPI 2 programmers This method is not precisely the same as lineMakeCall. It supplies TAPI with much of the same information, but parallel operations are not performed until ITBasicCallControl::Connect is called.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, Address Object, ITBasicCallControl::Dial, lineDial


ITAddress::CreateForwardInfoObject

The CreateForwardInfoObject method creates the forwarding information object and returns an ITForwardInformation interface pointer. This interface exposes methods that allow an application to control aspects of how a call is forwarded, such as whether internal calls will be handled differently than external calls.

HRESULT CreateForwardInfoObject(
  ITForwardInformation **ppForwardInfo
);

Parameters

ppForwardInfo
[out, retval] Pointer to ITForwardInformation interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppForwardInfo parameter is not a valid pointer.

Remarks

The application must set information on a newly created ITForwardInformation object before the object can be used.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, ITForwardInformation, Forward, get_CurrentForwardInfo, Address Object


ITAddress::EnumerateCalls

The EnumerateCalls method enumerates calls on the current address. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Calls method.

HRESULT EnumerateCalls(
  IEnumCall **ppCallEnum
);

Parameters

ppCallEnum
[out, retval] Pointer to an IEnumCall interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCallEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, ITAddress::get_Calls, Address Object


ITAddress::Forward

The Forward method forwards calls destined for the address according to the forwarding instructions contained in ITForwardInformation. If pForwardInfo is set to NULL, forwarding is canceled.

HRESULT Forward(
  ITForwardInformation *pForwardInfo,
  ITBasicCallControl *pCall
);

Parameters

pForwardInfo
[in] Pointer to ITForwardInformation interface, or set to NULL to cancel forwarding.
pCall
[in] Pointer to ITBasicCallControl interface for the consultation call, if required by the telephony environment. May be NULL if not required.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The address does not support forwarding, or pCall does not point to a valid call.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pForwardInfo or pCall parameter is not a valid pointer.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.
LINEERR_ | See LineForward for error codes returned from this TAPI 2.1 function.

Remarks

The information in pForwardInfo overrides any previous forwarding instructions.

If ITAddress::put_DoNotDisturb is called with fDoNotDisturb set to VARIANT_FALSE, all forwarding is canceled.

An application can determine whether non-NULL consultation call is required by calling ITAddressCapabilities::get_AddressCapability (AC_ADDRESSCAPFLAGS, plCapability) and checking whether the flag LINEADDRCAPFLAGS_FWDCONSULT, a member of LINEADDRCAPFLAGS_ Constants, has been set in plCapability. If it is set, a non-NULL value is required for the pCall parameter of the Forward method.

The Forward method is, in part, a COM wrapper for the TAPI 2.1 LineForward function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::get_CurrentForwardInfo, Forward overview, Address Object, LineForward


ITAddress::get_AddressName

The get_AddressName method gets the displayable name of the address.

HRESULT get_AddressName(
  BSTR *ppName
);

Parameters

ppName
[out, retval] Pointer to BSTR containing a displayable address name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppName parameter is not a valid pointer.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, Address Object


ITAddress::get_Calls

The get_Calls method creates a collection of calls currently active on the address. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateCalls method.

HRESULT get_Calls(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to a VARIANT containing an ITCollection of ITCallInfo interface pointers (call objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, EnumerateCalls, Address Object, ITCollection, ITCallInfo


ITAddress::get_CurrentForwardInfo

The get_CurrentForwardInfo method gets a pointer to the current forwarding information object.

HRESULT get_CurrentForwardInfo(
  ITForwardInformation **ppForwardInfo
);

Parameters

ppForwardInfo
[out, retval] Pointer to ITForwardInformation interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
LINEERR_INVALPOINTER | The ppForwardInfo parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, Address Object


ITAddress::get_DialableAddress

The get_DialableAddress method gets the BSTR which can be used to connect to this address. The BSTR corresponds to the destination address string that another application would use to connect to this address, such as a phone number or an e-mail name.

HRESULT get_DialableAddress(
  BSTR *pDialableAddress
);

Parameters

pDialableAddress
[out, retval] Pointer to BSTR containing the dialable address string. This will match the pDestAddress argument of ITAddress::CreateCall.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pDialableAddress parameter is not a valid pointer.

Remarks

The application must use SysFreeString to free the memory allocated for the pDialableAddress parameter.

The availability of this value depends on the service provider. For example, on an address exposed by the Unimodem service provider, this method will return an empty string instead of a phone number.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, ITAddress::CreateCall, Address Object, Dialable Addresses


ITAddress::get_DoNotDisturb

The get_DoNotDisturb method gets the current status of the do not disturb feature on the address. The do not disturb feature may not be available on all addresses.

HRESULT get_DoNotDisturb(
  VARIANT_BOOL *pfDoNotDisturb
);

Parameters

pfDoNotDisturb
[out, retval] If VARIANT_TRUE, the do not disturb feature has been activated. If VARIANT_FALSE, the do not disturb feature is not active.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OPERATIONUNAVAIL | Operation unavailable.
TAPI_E_NOTSUPPORTED | This operation is not supported on this address.
E_POINTER | The pfDoNotDisturb parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

For programmers familiar with TAPI 2.x: The DoNotDisturb feature is implemented using the "forward" feature, if present on the address. When get_DoNotDisturb is called, Tapi3.dll gets the LINEADDRESSSTATUS of the address object, and looks for its LINEFORWARD entries. If one such entry is found and if its dwDestAddressOffset member is 0 (zero), then DoNotDisturb is considered to be turned ON, and therefore VARIANT_TRUE is returned as the value for this method.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, put_DoNotDisturb, Address Object


ITAddress::get_MessageWaiting

The get_MessageWaiting method determines if the address has a message waiting.

HRESULT get_MessageWaiting(
  VARIANT_BOOL *pfMessageWaiting
);

Parameters

pfMessageWaiting
[out, retval] If VARIANT_TRUE is returned, a message is waiting; if VARIANT_FALSE is returned, no message is waiting.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pfMessageWaiting parameter is not a valid pointer.

Remarks

In TAPI 2.x, this maps to the flag LINEDEVSTATUSFLAGS_MSGWAIT being set or not in the member dwDevStatusFlags from the structure LINEDEVSTATUS.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, put_MessageWaiting, Address Object, LINEDEVSTATUS


ITAddress::get_ServiceProviderName

The get_ServiceProviderName method gets the name of the Telephony Service Provider (TSP) that supports this address: for example, Unimdm.tsp for the Unimodem service provider or H323.tsp for the H323 service provider.

HRESULT get_ServiceProviderName(
  BSTR *ppName
);

Parameters

ppName
[out, retval] Pointer to BSTR containing the service provider name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_NODRIVER | No service provider was found that supports the current address.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

You can retrieve the name of the provider in a TSP-dependent format using ITAddressCapabilities::get_AddressCapabilityString with AddressCapString set to ACS_PROVIDERSPECIFIC, which returns the string found in the dwProviderInfoOffset member of the TAPI 2.x LINEDEVCAPS structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, Address Object, ITAddressCapabilities::get_AddressCapabilityString, LINEDEVCAPS


ITAddress::get_State

The get_State method gets the current state of the address in pAddressState.

HRESULT get_State(
  ADDRESS_STATE *pAddressState
);

Parameters

pAddressState
[out, retval] Pointer to a member of ADDRESS_STATE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pAddressState parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, Address Object, ADDRESS_STATE


ITAddress::get_TAPIObject

The get_TAPIObject method gets a pointer to the TAPI object that owns this address.

HRESULT get_TAPIObject(
  ITTAPI **ppTapiObject
);

Parameters

ppTapiObject
[out, retval] Pointer to ITTAPI interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppTapiObject parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, Address Object


ITAddress::put_DoNotDisturb

The put_DoNotDisturb method sets the do not disturb status. The do not disturb feature may not be available on all addresses.

HRESULT put_DoNotDisturb(
  VARIANT_BOOL fDoNotDisturb
);

Parameters

fDoNotDisturb
[in] If VARIANT_TRUE, the do not disturb feature will be activated. If VARIANT_FALSE, the do not disturb feature will be deactivated and all forwarding canceled.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The fDoNotDisturb parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

The DoNotDisturb feature is implemented using forwarding. If put_DoNotDisturb is called with VARIANT_TRUE, Tapi3.dll creates a LINEFORWARD list with the mode set to LINEFORWARDMODE_UNCOND and only one LINEFORWARD item with the destination address set to NULL. If put_DoNotDisturb is called with VARIANT_FALSE, Tapi3.dll cancels forwarding completely on this address, even those forwarding rules set with ITAddress::Forward.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, get_DoNotDisturb, Address Object


ITAddress::put_MessageWaiting

The put_MessageWaiting method sets the status of the message waiting on the address.

HRESULT put_MessageWaiting(
  VARIANT_BOOL fMessageWaiting
);

Parameters

fMessageWaiting
[in] Status of message waiting to be set.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The fMessageWaiting parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

For programmers familiar with TAPI 2.x: This method turns on and off the flag LINEDEVSTATUSFLAGS_MSGWAIT in the dwDevStatusFlags member of the LINEDEVSTATUS structure by calling lineSetLineDevStatus.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, get_MessageWaiting, Address Object, LINEDEVSTATUS, lineSetLineDevStatus


ITAddress2

[This is preliminary documentation and subject to change.]

The ITAddress2 interface derives from the ITAddress interface. ITAddress2 adds methods to the Address object in order to support phone devices. All Address objects enumerated from TAPI 3.1 automatically implement this interface.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAddress2 methods | Description
get_Phones | Gets a collection of phone objects that can be used with this address. This method is intended for Visual Basic and scripting applications.
EnumeratePhones | Enumerates the phone objects corresponding to the phone devices that can be used with this address. This method is intended for C/C++ applications.
GetPhoneFromTerminal | Gets the phone object associated with the terminal.
get_EventFilter | Gets event filters for this address.
put_EventFilter | Sets event filters for this address.
EnumeratePreferredPhones | Enumerates the phone objects corresponding to the phone devices that are preferred for use with this address. This method is intended for C/C++ applications.
get_PreferredPhones | Returns a collection of phone objects corresponding to the phone devices that are preferred for use with this address. This method is intended for Visual Basic and scripting applications.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress


ITAddress2::EnumeratePhones

[This is preliminary documentation and subject to change.]

The EnumeratePhones method enumerates the phone objects corresponding to the phone devices that can be used with this address.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_Phones method.

HRESULT EnumeratePhones(
  IEnumPhone ** ppEnumPhone
);

Parameters

ppEnumPhone
[out,retval] Pointer to the new IEnumPhone interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumPhone parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | The method failed for unknown reasons.

Remarks

A phone device declares itself as being available on all addresses that support audio terminals by the TSP setting the PHONEFEATURE_GENERICPHONE bit in the dwPhoneFeatures member of the PHONECAPS structure. A phone device can also declare itself as being preferred to an address or set of addresses by returning address/line IDs using phoneGetID with device class tapi/line. If no phones are available for use with the address, this method produces an empty enumeration and returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress2, IEnumPhone


ITAddress2::EnumeratePreferredPhones

[This is preliminary documentation and subject to change.]

The EnumeratePreferredPhones method enumerates the preferred phone objects for this address.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_PreferredPhones method.

HRESULT EnumeratePreferredPhones(
  IEnumPhone ** ppEnumPhone
);

Parameters

ppEnumPhone
[out,retval] Pointer to the location where, on success, this method will place a pointer to an enumeration object that contains the returned list of phones.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumPhone parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the enumeration object.

Remarks

A phone device declares itself as being preferred to an address or set of addresses by returning address/line IDs using phoneGetID with device class tapi/line. If no phones are available for use with the address, this method produces an empty enumeration and returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress2


ITAddress2::GetPhoneFromTerminal

[This is preliminary documentation and subject to change.]

The GetPhoneFromTerminal method returns the phone object associated with the terminal. Only one phone can be associated with a terminal.

HRESULT GetPhoneFromTerminal(
  ITTerminal * pTerminal,
  ITPhone ** ppPhone
);

Parameters

pTerminal
[in] Pointer to the ITTerminal interface.
ppPhone
[out,retval] Pointer to the ITPhone interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress2, ITTerminal, ITPhone


ITAddress2::get_EventFilter

[This is preliminary documentation and subject to change.]

The get_EventFilter method retrieves the current filter settings for the current address and a given TAPI_EVENT value.

If no filters are set for an address, no event information for that address will be sent to the application.

HRESULT get_EventFilter(
  TAPI_EVENT TapiEvent,
  long lSubEvent,
  VARIANT_BOOL * pEnable
);

Parameters

TapiEvent
[in] The TAPI_EVENT descriptor of event type information being checked.
lSubEvent
[in] Subevent value. NULL if not applicable.
pEnable
[out,retval] Pointer to VARIANT_BOOL indicating whether the current event is required by the application.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress2, get_EventFilter


ITAddress2::get_Phones

[This is preliminary documentation and subject to change.]

The get_Phones method returns a VARIANT pointer to an ITCollection of phone objects corresponding to the phone devices that can be used with this address.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the EnumeratePhones method instead.

HRESULT get_Phones(
  VARIANT * pPhones
);

Parameters

pPhones
[out,retval] Pointer to a VARIANT containing an ITCollection of IEnumPhone interface pointers.

Remarks

A phone device declares itself as being available on all addresses that support audio terminals by the TSP setting the PHONEFEATURE_GENERICPHONE bit in the dwPhoneFeatures member of the PHONECAPS structure. A phone device can also declare itself as being preferred to an address or set of addresses by returning address/line IDs via phoneGetID with device class tapi/line. If no phones are available for use with the address, this method produces an empty collection and returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress2, EnumeratePhones


ITAddress2::get_PreferredPhones

[This is preliminary documentation and subject to change.]

The get_PreferredPhones method returns a collection of phone objects corresponding to the phone devices that are preferred for use with this address.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the EnumeratePreferredPhones method instead.

HRESULT get_PreferredPhones(
  VARIANT * pPhones
);

Parameters

pPhones
[out,retval] Pointer to a VARIANT containing an ITCollection of ITAddress2 interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pPhones parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the collection object.

Remarks

A phone device declares itself as being preferred to an address or set of addresses by returning address/line IDs using phoneGetID with device class tapi/line. If no phones are available for use with this address, the method produces an empty collection and returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress2


ITAddress2::put_EventFilter

[This is preliminary documentation and subject to change.]

The put_EventFilter method sets an event filter for the current address. If no event filters are set, the application will not be notified of events on this address.

HRESULT put_EventFilter(
  TAPI_EVENT TapiEvent,
  long lSubEvent,
  VARIANT_BOOL bEnable
);

Parameters

TapiEvent
[in] The TAPI_EVENT descriptor of the event type.
lSubEvent
[in] Subevent descriptor.
bEnable
[in] VARIANT_TRUE if the application requires notification of this event type. VARIANT_FALSE if the application does not require notifications for this event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress2, TAPI_EVENT


ITAddressCapabilities

The ITAddressCapabilities interface is used to obtain information about an address's capabilities. It is on the Address object, and an application can access it by calling QueryInterface on the Address object.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAddressCapabilities methods | Description
get_AddressCapability | Gets the capability value for a given ADDRESS_CAPABILITY.
get_AddressCapabilityString | Gets the capability string for a given ADDRESS_CAPABILITY_STRING.
get_CallTreatments | Gets the call treatment. This method is provided for Automation client applications, such as those written in Visual Basic and scripting languages.
EnumerateCallTreatments | Gets call treatments. This method is provided for applications written in C/C++ and Java.
get_CompletionMessages | Gets completion messages. This method is provided for Automation client applications, such as those written in Visual Basic and scripting languages.
EnumerateCompletionMessages | Gets completion messages. This method is provided for applications written in C/C++ and Java.
get_DeviceClasses | Gets device classes. This method is provided for Automation client applications, such as those written in Visual Basic and scripting languages.
EnumerateDeviceClasses | Gets device classes. This method is provided for applications written in C/C++ and Java.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Address Object


ITAddressCapabilities::EnumerateCallTreatments

The EnumerateCallTreatments method gets call treatments. This method is provided for applications written in C/C++ and Java.

HRESULT EnumerateCallTreatments(
  IEnumBstr **ppEnumCallTreatment
);

Parameters

ppEnumCallTreatment
[out, retval] Pointer to call treatment enumeration.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object


ITAddressCapabilities::EnumerateCompletionMessages

The EnumerateCompletionMessages method gets completion messages. This method is provided for applications written in C/C++ and Java.

HRESULT EnumerateCompletionMessages(
  IEnumBstr **ppEnumCompletionMessage
);

Parameters

ppEnumCompletionMessage
[out, retval] Pointer to enumeration of completion messages.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object


ITAddressCapabilities::EnumerateDeviceClasses

The EnumerateDeviceClasses method gets device classes. This method is provided for applications written in C/C++ and Java.

HRESULT EnumerateDeviceClasses(
  IEnumBstr **ppEnumDeviceClass
);

Parameters

ppEnumDeviceClass
[out, retval] Pointer to enumeration of device classes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object


ITAddressCapabilities::get_AddressCapability

The get_AddressCapability method gets the capability value for a given ADDRESS_CAPABILITY.

HRESULT get_AddressCapability(
  ADDRESS_CAPABILITY AddressCap,
  long *plCapability
);

Parameters

AddressCap
[in] Descriptor for desired address capability.
plCapability
[out, retval] Value of address capability.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The AddressCap parameter is not valid.
E_POINTER | The plCapability parameter in not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object, ADDRESS_CAPABILITY


ITAddressCapabilities::get_AddressCapabilityString

The get_AddressCapabilityString method gets the capability string for a given ADDRESS_CAPABILITY_STRING.

HRESULT get_AddressCapabilityString(
  ADDRESS_CAPABILITY_STRING AddressCapString,
  BSTR *ppCapabilityString
);

Parameters

AddressCapString
[in] Descriptor for desired address capability string.
ppCapabilityString
[out, retval] Pointer to BSTR value of address capability. NULL is a possible return value if the TSP does not provide a value for AddressCapString.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The AddressCapString parameter is not valid.
E_POINTER | The ppCapabilityString parameter is not a valid pointer.
TAPI_E_NOTSUPPORTED | TAPI version is not 3.0 or higher.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCapabilityString parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object, ADDRESS_CAPABILITY_STRING


ITAddressCapabilities::get_CallTreatments

The get_CallTreatments method gets call treatments. This method is provided for Automation client applications, such as those written in Visual Basic and scripting languages.

HRESULT get_CallTreatments(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to a VARIANT containing an ITCollection of ITCallInfo interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_INVALCALLSTATE | Call state must be CS_IDLE.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object


ITAddressCapabilities::get_CompletionMessages

The get_CompletionMessages gets completion messages. This method is provided for Automation client applications, such as those written in Visual Basic and scripting languages.

HRESULT get_CompletionMessages(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing completion messages.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object


ITAddressCapabilities::get_DeviceClasses

The get_DeviceClasses method gets device classes. This method is provided for Automation client applications, such as those written in Visual Basic and scripting languages.

HRESULT get_DeviceClasses(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing device classes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressCapabilities, Address Object


ITAddressEvent

The ITAddressEvent interface contains methods that retrieve the description of address events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_ADDRESS, the method's pEvent parameter is an IDispatch pointer for the ITAddressEvent interface. The methods of this interface can be used to retrieve information concerning the type of event, which address the event has occurred on, and for which terminal.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_ADDRESS event to enable reception of address events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAddressEvent methods | Description
get_Address | Gets a pointer to the ITAddress interface.
get_Event | Gets the ADDRESS_EVENT descriptor of an event.
get_Terminal | Gets a pointer to the ITTerminal interface.

Remarks

Certain events on PnP devices will not be received until after the first time static terminals are enumerated using ITTerminalSupport::EnumerateStaticTerminals or ITTerminalSupport::get_StaticTerminals.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITAddress, ADDRESS_EVENT, ITTerminal, Address Object, Register Events code snippet, Event Notification overview, Device Events overview


ITAddressEvent::get_Address

The get_Address method gets a pointer to the ITAddress object involved in an event.

HRESULT get_Address(
  ITAddress **ppAddress
);

Parameters

ppAddress
[out, retval] Pointer to an ITAddress interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppAddress parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressEvent, Address Object


ITAddressEvent::get_Event

The get_Event method gets the ADDRESS_EVENT descriptor of an event.

HRESULT get_Event(
  ADDRESS_EVENT *pEvent
);

Parameters

pEvent
[out, retval] Pointer to the ADDRESS_EVENT descriptor of an event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pEvent parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pEvent parameter is not a valid pointer.

Remarks

Certain events on PnP devices, such as AE_NEWTERMINAL and AE_REMOVETERMINAL, will not be received until after the first time static terminals are enumerated using ITTerminalSupport::EnumerateStaticTerminals or ITTerminalSupport::get_StaticTerminals.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressEvent, Address Object, ADDRESS_EVENT


ITAddressEvent::get_Terminal

The get_Terminal method gets a pointer to the ITTerminal interface associated with the event.

HRESULT get_Terminal(
  ITTerminal ** ppTerminal
);

Parameters

ppTerminal
[out, retval] Pointer to ITTerminal interface, or NULL if the event does not refer to a terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppTerminal parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressEvent, Address Object


ITAddressTranslation

The ITAddressTranslation interface provides methods that allow translation of a calling address into a different format. For example, an application may need to translate an address from canonical to dialable prior to making a call.

The most common use of this interface is to obtain the pDestAddress string needed for ITAddress::CreateCall. The addresses to be translated are mainly phone numbers in canonical format.

The ITAddressTranslation interface is exposed on the Address Object. A pointer can be obtained by calling QueryInterface on ITAddress.

For additional information, see Address Translation and Dialable Addresses.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAddressTranslation methods | Description
TranslateAddress | Creates the address translation information interface.
TranslateDialog | Invokes the control panel's telephony applet.
EnumerateLocations | Enumerates the currently available address locations.
get_Locations | Creates a collection of currently available address locations. This method is provided for Automation client applications, such as those written in Visual Basic.
EnumerateCallingCards | Enumerates calling cards associated with the address.
get_CallingCards | Creates a collection of calling cards associated with the address. This method is provided for Automation client applications, such as those written in Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Address Object, ITAddress, ITAddressTranslationInfo, Address Translation, Dialable Addresses, lineTranslateAddress, lineGetTranslateCaps


ITAddressTranslation::EnumerateCallingCards

The EnumerateCallingCards method enumerates calling cards associated with the address. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_CallingCards method.

HRESULT EnumerateCallingCards(
  IEnumCallingCard **ppEnumCallingCard
);

Parameters

ppEnumCallingCard
[out, retval] Pointer to IEnumCallingCard interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumCallingCard parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

This method is a COM wrapper for the TAPI 2.1 LineGetTranslateCaps function, and takes calling card information from the LINETRANSLATECAPS structure returned by that function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslation, Address Object


ITAddressTranslation::EnumerateLocations

The EnumerateLocations method enumerates the currently available address locations. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Locations method.

HRESULT EnumerateLocations(
  IEnumLocation **ppEnumLocation
);

Parameters

ppEnumLocation
[out, retval] Pointer to IEnumLocation object created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumLocations parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to create object.

Remarks

The EnumerateLocations method is a COM wrapper for the TAPI 2.1 LineGetTranslateCaps function, and takes location information from the LINETRANSLATECAPS structure returned by that function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslation, Address Object


ITAddressTranslation::TranslateAddress

The TranslateAddress method creates the address translation information interface. The primary goal of the TranslateAddress method is to obtain the pDestAddress string (dialable address) needed as a parameter for ITAddress::CreateCall. The TranslateAddress method returns the dialable address indirectly, as one of the properties of an ITAddressTranslationInfo object.

HRESULT TranslateAddress(
  BSTR pAddressToTranslate,
  long lCard,
  long lTranslateOptions,
  ITAddressTranslationInfo **ppTranslated
);

Parameters

pAddressToTranslate
[in] Pointer to BSTR containing address that requires translation.
lCard
[in] Calling card used for translation.
lTranslateOptions
[in] Indicator of translation options, see LINETRANSLATEOPTION__Constants.
ppTranslated
[out, retval] Pointer to newly created ITAddressTranslationInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTranslated parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | The method failed for unknown reasons.
E_INVALIDARG | The lTranslateOptions value is not valid.
TAPI_E_NODRIVER | This address has no TSP associated with it.
TAPI_E_REGISTRY_SETTING_CORRUPT | The registry is corrupt.
TAPI_E_OPERATIONFAILED | The method failed with TAPI.
TAPI_E_RESOURCEUNAVAIL | The TSP is not available.
TAPI_E_INVALCARD | The card number is not valid.

Remarks

The application must use SysAllocString to allocate memory for pAddressToTranslate and use SysFreeString to free the memory when the variable is no longer needed.

The TranslateAddress method is a COM wrapper for the TAPI 2.1 LineTranslateAddress function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslation, Address Object, Dialable Addresses


ITAddressTranslation::TranslateDialog

The TranslateDialog method displays an application-modal dialog box that allows the user to change the current location of a phone number about to be dialed, adjust location and calling card parameters, and see the effect.

HRESULT TranslateDialog(
  TAPIHWND hwndOwner,
  BSTR pAddressIn
);

Parameters

hwndOwner
[in] A handle to a window to which the dialog box is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.
pAddressIn
[in] A pointer to BSTR containing a phone number that is used to show the effect of the user's changes on the location parameters. The number must be in canonical format. This pointer can be left NULL, in which case the phone number portion of the dialog box is not displayed. If the pAddressIn parameter contains a subaddress or name field or additional addresses separated from the first address by ASCII CR and LF characters, only the first address is used in the dialog box.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The hwndOwner parameter is not a valid handle or the pAddressIn parameter is not a valid phone number.
E_POINTER | The pAddressIn parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | An unexpected error occurred.
TAPI_E_REGISTRY_SETTING_CORRUPT | The registry settings for address translation are not valid.
TAPI_E_NODRIVER | No TSP exists that can do translation for this address.
TAPI_E_INUSE | The dialog is already open and in use.
TAPI_E_INVALADDRESS | The current address is not valid.
TAPI_E_OPERATIONFAILED | TAPI was not able to complete the operation.

Remarks

The application must use SysAllocString to allocate memory for pAddressIn and use SysFreeString to free the memory when the variable is no longer needed.

The TranslateDialog method is a COM wrapper for the TAPI 2.1 LineTranslateDialog function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslation, Address Object, LineTranslateDialog


ITAddressTranslation::get_CallingCards

The get_CallingCards method creates a collection of calling cards associated with the address. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateCallingCards method.

HRESULT get_CallingCards(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITCallingCard interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The get_CallingCards method is a COM wrapper for the TAPI 2.1 LineGetTranslateCaps function, and takes calling card information from the LINETRANSLATECAPS structure returned by that function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Address Object, LineGetTranslateCaps, LINETRANSLATECAPS, ITCollection, ITCallingCard


ITAddressTranslation::get_Locations

The get_Locations method creates a collection of currently available address locations. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateLocations method.

HRESULT get_Locations(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITLocationInfo interface pointers (location objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The get_Locations method is a COM wrapper for the TAPI 2.1 LineGetTranslateCaps function, and takes location information from the LINETRANSLATECAPS structure returned by that function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslation, EnumerateLocations, Address Object, ITCollection, ITLocationInfo


ITAddressTranslationInfo

The ITAddressTranslationInfo interface is used to determine the address translation information. A pointer to it is obtained by calling ITAddressTranslation::TranslateAddress.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAddressTranslationInfo methods | Description
get_DialableString | Gets a string that contains a dialable number.
get_DisplayableString | Gets a string contains a displayable verion of the dialable number.
get_CurrentCountryCode | Gets the current country code.
get_DestinationCountryCode | Gets the country code for the call destination.
get_TranslationResults | Gets the translated dialable calling address.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Address Object, ITAddressTranslation, lineTranslateAddress


ITAddressTranslationInfo::get_CurrentCountryCode

The get_CurrentCountryCode method gets the current country code.

HRESULT get_CurrentCountryCode(
  long *CountryCode
);

Parameters

CountryCode
[out, retval] Pointer to country code.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The CountryCode parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

Corresponds to the dwCurrentCountry member of TAPI 2's LINETRANSLATEOUTPUT structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslationInfo, Address Object


ITAddressTranslationInfo::get_DestinationCountryCode

The get_DestinationCountryCode method gets the country code for the call destination.

HRESULT get_DestinationCountryCode(
  long *CountryCode
);

Parameters

CountryCode
[out, retval] Pointer to destination country code.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The CountryCode parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

Corresponds to the dwDestCountry member of TAPI 2's LINETRANSLATEOUTPUT structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslationInfo, Address Object


ITAddressTranslationInfo::get_DialableString

The get_DialableString method gets a string that contains a dialable number. Typically, this number is then used as the pDestAddress argument in ITAddress::CreateCall.

HRESULT get_DialableString(
  BSTR *ppDialableString
);

Parameters

ppDialableString
[out, retval] Pointer to BSTR containing representation of dialable string.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppDialableString parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppDialableString parameter.

Corresponds to the dwDialableStringSize and dwDialableStringOffset members of TAPI 2's LINETRANSLATEOUTPUT structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslationInfo, Address Object


ITAddressTranslationInfo::get_DisplayableString

The get_DisplayableString method gets a string that contains a displayable version of the dialable number.

HRESULT get_DisplayableString(
  BSTR *ppDisplayableString
);

Parameters

ppDisplayableString
[out, retval] Pointer to BSTR containing representation of displayable string.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppDisplayableString parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppDisplayableString parameter.

Corresponds to the dwDisplayableStringSize and dwDisplayableStringOffset members of TAPI 2's LINETRANSLATEOUTPUT structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslationInfo, Address Object


ITAddressTranslationInfo::get_TranslationResults

The get_TranslationResults method gets the results of a translation operation.

HRESULT get_TranslationResults(
  long *plResults
);

Parameters

plResults
[out, retval] Indicates the information derived from the translation process, which may assist the application in presenting user-interface elements. This value uses one of the LINETRANSLATERESULT_ Constants.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plResults parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

Corresponds to the dwTranslateResults member of TAPI 2's LINETRANSLATEOUTPUT structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslationInfo, Address Object


ITAllocatorProperties

The ITAllocatorProperties interface exposes the buffer allocator properties of the Media Streaming Terminal (MST) to an end-user or server application. An application needs to tune the sample size for a particular protocol. The decision concerning appropriate properties is highly implementation dependent.

This interface is exposed on the Terminal Object by the associated Media Service Provider. If it exists, a QueryInterface on any Terminal interface, such as ITTerminal, can be used to obtain an ITAllocatorProperties pointer.

Methods in Vtable Order

ITAllocatorProperties methods | Description
SetAllocatorProperties | Forces MST to use the values input during filter negotiation.
GetAllocatorProperties | Gets the negotiated allocator properties following a connection.
SetAllocateBuffers | Sets whether buffers must be supplied.
GetAllocateBuffers | Gets whether buffers must be supplied.
SetBufferSize | Sets the size of the allocator buffer.
GetBufferSize | Gets the size of the allocator buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITAllocatorProperties::GetAllocateBuffers

The GetAllocateBuffers method determines whether the current allocator buffers can be retrieved. If it returns FALSE, the sample that the MST allocated doesn't have any buffers and they must be supplied before Update is called on the samples.

HRESULT GetAllocateBuffers(
  BOOL *pbAllocBuffers
);

Parameters

pbAllocBuffers
[out] Indicates whether allocator buffers have been set.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAllocatorProperties


ITAllocatorProperties::GetAllocatorProperties

The GetAllocatorProperties method gets the current values for the allocator properties after connection and provides the negotiated values. This method is invalid before connection. The MST will accept any values suggested by the connected filters.

HRESULT GetAllocatorProperties(
  ALLOCATOR_PROPERTIES *pAllocProperties
);

Parameters

pAllocProperties
[out] Pointer to current allocator values.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAllocatorProperties


ITAllocatorProperties::GetBufferSize

The GetBufferSize method gets the size of the allocator buffer.

HRESULT GetBufferSize(
  DWORD *pBufferSize
);

Parameters

pBufferSize
[out] Size of current allocator buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAllocatorProperties


ITAllocatorProperties::SetAllocateBuffers

The SetAllocateBuffers method determines whether the current allocator buffers must be set. This property is TRUE by default. If set FALSE, the sample that the MST allocated doesn't have any buffers and they must be supplied before Update is called on the samples.

HRESULT SetAllocateBuffers(
  BOOL bAllocBuffers
);

Parameters

bAllocBuffers
[in] Boolean indicator of whether allocator buffers must be set.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAllocatorProperties


ITAllocatorProperties::SetAllocatorProperties

The SetAllocatorProperties method must be called before connection and will force the MST to use these values during filter negotiation. If the connecting filter doesn't accept these values, the connection is not established.

HRESULT SetAllocatorProperties(
  ALLOCATOR_PROPERTIES *pAllocProperties
);

Parameters

pAllocProperties
[in] Pointer to the allocator buffer.

Remarks

This method should be used with extreme care. The quality of the sound may suffer if the values entered for this method are not optimal for the MSP. Therefore, the application should know exactly the properties preferred by the MSP before calling this method. Under Windows 2000, properties entered during calls to this method are ignored if they are not optimal. Under Whistler, these values are not ignored and the application must be more knowledgeable.

If the application is only concerned with setting consistent buffer sizes, the ITAllocatorProperties::SetBufferSize method should be used instead. This guarantees the application is provided with the specified buffer size.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAllocatorProperties


ITAllocatorProperties::SetBufferSize

The SetBufferSize method sets the size of the allocator buffer.

HRESULT SetBufferSize(
  DWORD BufferSize
);

Parameters

BufferSize
[in] Size of the allocator buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAllocatorProperties


ITAMMediaFormat

The ITAMMediaFormat interface sets and gets DirectShow media format. The format is described using the AM_MEDIA_TYPE structure. This interface is exposed on a Terminal Object only if an MSP is involved in terminal creation and implements this interface.

On addresses where a variety of formats are supported (such as Wave MSP addresses, which are used on most modems and voice boards), this media format must be set or the terminal will not be able to connect.

For other addresses, such as those implemented over IP, the format may be fixed/predetermined. In that case, a call to set format will fail if the format is not the same as the predetermined format.

Methods in Vtable Order

IUnknown Methods

ITAMMediaFormat methods | Description
get_MediaFormat | Gets the media format.
put_MediaFormat | Sets the media format.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object, AM_MEDIA_TYPE structure


ITAMMediaFormat::get_MediaFormat

The get_MediaFormat method gets the media format.

HRESULT get_MediaFormat(
  AM_MEDIA_TYPE **ppmt
);

Parameters

ppmt
[out, retval] Pointer to an array of AM_MEDIA_TYPE structures.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAMMediaFormat, put_MediaFormat, Terminal Object, AM_MEDIA_TYPE structure


ITAMMediaFormat::put_MediaFormat

The put_MediaFormat method sets the media format.

HRESULT put_MediaFormat(
  const AM_MEDIA_TYPE *pmt
);

Parameters

pmt
[in] Pointer to AM_MEDIA_TYPE structure.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

On addresses where a variety of formats are supported (such as Wave MSP addresses, which are used on most modems and voice boards), this call is mandatory or the terminal will not be able to connect.

For other addresses, such as those implemented over IP, the format may be fixed/predetermined. In that case, this call will fail if the format is not the same as the predetermined format. To retrieve such a predetermined format, an application can use get_MediaFormat.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAMMediaFormat, get_MediaFormat, Terminal Object, AM_MEDIA_TYPE structure


ITASRTerminalEvent

[This is preliminary documentation and subject to change.]

The ITASRTerminalEvent interface contains methods that retrieve the description of Automatic Speech Recognition terminal events that have occurred. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_ASRTERMINAL, the method's pEvent parameter is an IDispatch pointer for the ITASRTerminalEvent interface.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes TE_ASRTERMINAL to enable reception of Automatic Speech Recognition terminal events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITASRTerminalEvent methods | Description
get_Terminal | Returns a pointer to the ITTerminal interface for the terminal on which the event occurred.
get_Call | Returns a pointer to the ITCallInfo interface for the call object involved in the terminal event.
get_Error | Returns an HRESULT cast of the error associated with the terminal event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, ITTerminal, ITTAPIEventNotification::Event, ITTAPI::put_EventFilter, TAPI_EVENT


ITASRTerminalEvent::get_Call

[This is preliminary documentation and subject to change.]

The get_Call method returns a pointer to the ITCallInfo interface for the call object involved in the terminal event.

HRESULT get_Call(
  ITCallInfo ** ppCall
);

Parameters

ppCall
[out,retval] Pointer to ITCallInfo interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITASRTerminalEvent, ITCallInfo


ITASRTerminalEvent::get_Error

[This is preliminary documentation and subject to change.]

The get_Error method returns an HRESULT cast of the error associated with the terminal event.

HRESULT get_Error(
  HRESULT * phrErrorCode
);

Parameters

phrErrorCode
[out,retval] Pointer to error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITASRTerminalEvent


ITASRTerminalEvent::get_Terminal

[This is preliminary documentation and subject to change.]

The get_Terminal method returns a pointer to the ITTerminal interface for the terminal on which the event occurred.

HRESULT get_Terminal(
  ITTerminal ** ppTerminal
);

Parameters

ppTerminal
[out,retval] Pointer to ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITASRTerminalEvent, ITTerminal


ITAutomatedPhoneControl

[This is preliminary documentation and subject to change.]

The ITAutomatedPhoneControl is a fully OLE automatable and scriptable interface exposed by the TAPI phone object. When a phone device is opened with owner privilege, you can call the QueryInterface method on the ITPhone interface to obtain an ITAutomatedPhoneControl interface pointer.

This interface performs several high-level phone-related functions:

  • Enable and configure automated control of the phone's tones and rings based on input from the phone's hookswitch and buttons.
  • Enable and configure automated call handling based on the phone's hookswitch state. For example, when the phone goes onhook while it is handling a connected call, the phone object can automatically invoke ITBasicCallControl::Disconnect on that call.
  • Generate specific tones on the audio devices associated with the phone, without accessing any audio APIs directly. The tone control allows an application to play tones on the audio devices associated with the phone, outside of the context of a call. Because these tones are not transmitted on any call, they are independent of the audio streaming functionality accessed through terminals.
  • Ring the phone without requiring information on whether the phone has a ringer and, if the phone has a ringer, determine the types of rings the phone supports.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAutomatedPhoneControl methods | Description
StartTone | Outputs tones.
StopTone | Stops any tone that is currently being played.
get_Tone | Gets the type of tone, if any, currently being played.
StartRinger | Starts the phone's ringer.
StopRinger | Stops the phone's ringer.
get_Ringer | Gets whether the phone is currently ringing.
put_PhoneHandlingEnabled | Enables or disables all automatic phone interaction features for this phone.
get_PhoneHandlingEnabled | Gets the current value of the PhoneHandlingEnabled property.
put_AutoEndOfNumberTimeout | Sets the current value of the AutoEndOfNumberTimeout property.
get_AutoEndOfNumberTimeout | Gets the current value of the AutoEndOfNumberTimeout property.
put_AutoDialtone | Enables or disables automatic dial tone response for this phone.
get_AutoDialtone | Gets the automatic dial tone status for this phone.
put_AutoStopTonesOnOnHook | Enables or disables automatic tone termination for this phone.
get_AutoStopTonesOnOnHook | Gets the automatic tone termination status for this phone.
put_AutoStopRingOnOffHook | Sets the current value of the AutoStopRingOnOffHook property.
get_AutoStopRingOnOffHook | Gets the current value of the AutoStopRingOnOffHook property.
put_AutoKeypadTones | Enables or disables automatic phone keypad feedback tone generation for this phone.
get_AutoKeypadTones | Gets automatic phone keypad feedback tone generation status for this phone.
put_AutoKeypadTonesMinimumDuration | Sets how long keypad tones play on PBS_DOWN.
get_AutoKeypadTonesMinimumDuration | Gets how long keypad tones play on PBS_DOWN.
put_AutoVolumeControl | Enables or disables automatic phone volume control for this phone.
get_AutoVolumeControl | Gets the current value of the AutoVolumeControl property.
put_AutoVolumeControlStep | Sets the amount that the phone volume is adjusted when the volume button is pressed.
get_AutoVolumeControlStep | Gets the amount that the phone volume is adjusted when the volume button is pressed.
put_AutoVolumeControlRepeatDelay | Sets the delay, in milliseconds, before a volume button starts repeating when it is held down.
get_AutoVolumeControlRepeatDelay | Gets the delay, in milliseconds, before a volume buttion starts repeating when it is held down.
put_AutoVolumeControlRepeatPeriod | Sets the period, in milliseconds, of button repeats when a volume button is held down.
get_AutoVolumeControlRepeatPeriod | Gets the current value of the AutoVolumeControlRepeatDelay property.
SelectCall | Selects the current phone onto a call.
UnselectCall | Removes the phone from the call.
EnumerateSelectedCalls | Gets an enumerator object indicating which calls are currently selected on this phone. This method is intended for C/C++ applications.
get_SelectedCalls | Gets a VARIANT containing a pointer to a collection object indicating which calls are currently selected on this phone. This method is intended for Visual Basic and scripting applications.

Remarks

An ITAutomatedPhoneControl pointer becomes invalid when the ITPhone::Close method is called.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone


ITAutomatedPhoneControl::EnumerateSelectedCalls

[This is preliminary documentation and subject to change.]

The EnumerateSelectedCalls method retrieves an enumerator object indicating which calls are currently selected on this phone. See ITAutomatedPhoneControl::SelectCall for more information.

This method is intended for C and C++ programmers. Applications written in Visual Basic, Java, or various scripting languages should use the get_SelectedCalls method instead.

HRESULT EnumerateSelectedCalls(
  IEnumCall ** ppCallEnum
);

Parameters

ppCallEnum
[out,retval] Pointer to the IEnumCall interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITAutomatedPhoneControl::SelectCall


ITAutomatedPhoneControl::SelectCall

[This is preliminary documentation and subject to change.]

The SelectCall method selects the current phone object onto the Call object pointed to by the pCall parameter.

HRESULT SelectCall(
  ITCallInfo * pCall,
  VARIANT_BOOL fSelectDefaultTerminals
);

Parameters

pCall
[in] Pointer to the ITCallInfo interface.
fSelectDefaultTerminals
[in] If VARIANT_TRUE, use default terminals. For more information, see the following Remarks section.

Remarks

The application must have owner privilege on both the call and the phone for this method to return success. If the phone is not already open with owner privilege, this method fails.

If the fSelectDefaultTerminals parameter is set to VARIANT_TRUE, this method retrieves all the default terminals associated with the phone and attempts to select them on the call. If instantiation of one of the terminals fails, or if selection of one of the terminals on the call fails, then the entire SelectCall method will return failure, and the call will not be selected on the phone. If this is not the required behavior for an application, then the application should pass in VARIANT_FALSE for the fSelectDefaultTerminals parameter and handle terminal selection separately.

On successful completion of this method, the phone object keeps a reference to the call object (that is, it calls the AddRef method on ITCallInfo).

For Whistler, only one call at a time can be selected on a phone. Future versions of TAPI may support simultaneous selection of multiple calls for use with phones that support multiple call appearances.

Note that a call can be unselected in two ways: (1) the application can invoke ITAutomatedPhoneControl::UnselectCall, or (2) the phone object itself can invoke ITAutomatedPhoneControl::UnselectCall. See the following list for information on when this happens.

After this method completes successfully, the following handling is performed on the selected call:

  • When the phone goes onhook, the phone object calls ITBasicCallControl::Disconnect on any currently handled call that is not already in the CS_DISCONNECTED call state.
  • If a selected call reaches the CS_DISCONNECTED call state, then the phone object automatically unselects the call using the ITAutomatedPhoneControl::UnselectCall method.
  • If the phone is closed, any selected call is automatically unselected from that phone.
  • When the phone goes offhook, or a call is selected when the phone is offhook, the phone object calls ITBasicCallControl::Answer on the currently handled call if it is in the CS_OFFERING call state.
  • The phone object calls ITAutomatedPhoneControl::StartTone( PT_RINGBACK, 0 ) on itself when a call is selected on it in the CS_INPROGRESS call state and the phone is offhook, or when a call that has been selected on the phone enters the CS_INPROGRESS call state and the phone is offhook.
  • The phone object calls ITAutomatedPhoneControl::StopTone on itself when a call is selected on it in the CS_CONNECTED call state, or when a call that has been selected on the phone enters the CS_CONNECTED call state.
  • The phone object calls ITAutomatedPhoneControl::StartRinger( 0, 0 ) on itself when a call is selected on it in the CS_OFFERING, CS_INPROGRESS, or CS_CONNECTED call state and the phone is onhook. This also occurs when a call that has been selected on the phone enters the CS_OFFERING, CS_INPROGRESS, or CS_CONNECTED call state and the phone is onhook.

Depending on the circumstances, the phone object performs one of the following actions when a call is selected on it in the CS_DISCONNECTED call state, or when a call that has been selected on the phone enters the CS_DISCONNECTED call state.

  • If the phone is onhook, then the phone object calls ITAutomatedPhoneControl::StopRinger on itself.
  • If the phone is offhook and the CS_DISCONNECTED call state event has cause equal to CEC_DISCONNECT_BUSY, then the phone object calls ITAutomatedPhoneControl::StartTone( PT_BUSY, 0 ).
  • If the phone is offhook and the CS_DISCONNECTED call state event has cause equal to CEC_DISCONNECT_NORMAL, then the phone object calls ITAutomatedPhoneControl::StopTone.
  • If the phone is offhook and the CS_DISCONNECTED call state event has neither cause CEC_DISCONNECT_BUSY nor cause CEC_DISCONNECT_NORMAL, then the phone object calls ITAutomatedPhoneControl::StartTone( PT_ERROR, 0 ).

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITBasicCallControl, ITCallInfo


ITAutomatedPhoneControl::StartRinger

[This is preliminary documentation and subject to change.]

The StartRinger method starts the phone's ringer, specifying the ring mode and the duration of the ring.

HRESULT StartRinger(
  long lRingMode,
  long lDuration
);

Parameters

lRingMode
[in] Ring mode. The exact meaning of this value is device-dependent. For more information, see the following Remarks section.
lDuration
[in] Length of ring.

Remarks

If you specify the value zero in the lRingMode parameter, and the phone doesn't have a ringer device, the StartRinger method attempts to play the ringing sound on the system's default audio render device. Examples of default devices include sound card speakers and a USB phone's audio render device. For more information, see PHONECAPS_LONG.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl


ITAutomatedPhoneControl::StartTone

[This is preliminary documentation and subject to change.]

The StartTone method sends control tones.

HRESULT StartTone(
  PHONE_TONE Tone,
  long lDuration
);

Parameters

Tone
[in] PHONE_TONE descriptor of the type of tone to send, such as PT_KEYPADONE.
lDuration
[in] Duration, in milliseconds, of the tone being sent.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl


ITAutomatedPhoneControl::StopRinger

[This is preliminary documentation and subject to change.]

The StopRinger method ceases any incoming ring that is currently being produced. If no ring is being produced, the method performs no action and returns success.

HRESULT StopRinger( );

Parameters

This method has no parameters.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl


ITAutomatedPhoneControl::StopTone

[This is preliminary documentation and subject to change.]

The StopTone method ceases any tone that is currently being played. If no tone is being played, the method performs no action and returns success.

HRESULT StopTone( );

Parameters

This method has no parameters.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl


ITAutomatedPhoneControl::UnselectCall

[This is preliminary documentation and subject to change.]

The UnselectCall method removes the specified call from this phone object, releasing the phone object's reference to the call object. The phone object performs no further call control handling on the call object once the call object has been successfully unselected. See ITAutomatedPhoneControl::SelectCall for more information.

HRESULT UnselectCall(
  ITCallInfo * pCall
);

Parameters

pCall
[in] Pointer to the ITCallInfo interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITCallInfo, ITAutomatedPhoneControl::SelectCall


ITAutomatedPhoneControl::get_AutoDialtone

[This is preliminary documentation and subject to change.]

The get_AutoDialtone method retrieves the current value of the AutoDialtone property. When this feature is enabled, the phone going offhook results in a dial tone produced on the audio render device associated with the phone. No dial tone is produced if the phone was ringing when it went offhook.

HRESULT get_AutoDialtone(
  VARIANT_BOOL * pfEnabled
);

Parameters

pfEnabled
[out,retval] If VARIANT_TRUE, auto dial tone is enabled. If VARIANT_FALSE, auto dial tone is disabled.

Remarks

The AutoDialtone property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoDialtone property at any time. The reconfiguration takes effect the next time the phone goes offhook.

All dial tone generation ceases when an invocation of ITAutomatedPhoneControl::SelectCall succeeds; dial tone generation remains suspended until the call is unselected.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITAutomatedPhoneControl::SelectCall, put_AutoDialtone, put_PhoneHandlingEnabled


ITAutomatedPhoneControl::get_AutoEndOfNumberTimeout

[This is preliminary documentation and subject to change.]

The get_AutoEndOfNumberTimeout method retrieves the current value of the AutoEndOfNumberTimeout property. The property specifies how long to wait after a digit has been pressed before it is assumed that the entire number has been gathered.

HRESULT get_AutoEndOfNumberTimeout(
  long * plTimeout
);

Parameters

plTimeout
[out,retval] Time-out interval to wait, in milliseconds (ms). The default value is 3000 ms.

Remarks

A value of 0 turns off this timeout and bases the end-of-number detection solely on the user pressing the # or SEND button.

End-of-number-detection ceases (without a detection event) when an invocation of ITAutomatedPhoneControl::SelectCall succeeds, and detection remains suspended until the call is unselected.

The AutoEndOfNumberTimeout property controls only what happens after at least one keypad button has been pressed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoEndOfNumberTimeout, ITAutomatedPhoneControl::SelectCall


ITAutomatedPhoneControl::get_AutoKeypadTones

[This is preliminary documentation and subject to change.]

The get_AutoKeypadTones method gets the AutoKeypadTones property for this phone. When this feature is enabled, a digit tone is automatically played whenever a keypad button is pressed.

HRESULT get_AutoKeypadTones(
  VARIANT_BOOL * pfEnabled
);

Parameters

pfEnabled
[out,retval] VARIANT_TRUE if automatic phone keypad feedback tone generation is enabled for this phone. VARIANT_FALSE if automatic phone keypad feedback tone generation is disabled for this phone.

Remarks

If the phone device reports a button press as PBS_DOWN, then the tone is played until the phone device reports a PBS_UP event or until the minimum duration has expired, whichever is longer. (The minimum duration is determined by the AutoKeypadTonesMinimumDuration property.)

Keypad tone generation will occur only when the phone is offhook. If another tone, such as ringback, is currently playing, the keypad tone will interrupt that tone and automatically restore it after the keypad tone has finished.

The AutoKeypadTones property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoKeypadTones property at any time. The reconfiguration takes effect the next time the phone keypad button is pressed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoKeypadTones, put_PhoneHandlingEnabled, put_AutoKeypadTonesMinimumDuration


ITAutomatedPhoneControl::get_AutoKeypadTonesMinimumDuration

[This is preliminary documentation and subject to change.]

The get_AutoKeypadTonesMinimumDuration method retrieves the current value of the AutoKeypadTonesMinimumDuration property. The property specifies how long to play keypad tones on PBS_DOWN.

HRESULT get_AutoKeypadTonesMinimumDuration(
  long * plDuration
);

Parameters

plDuration
[out,retval] Minimum duration of keypad tones, in milliseconds (ms). The default value is 250 ms. If the minimum duration elapses without a PBS_UP event, the keypad tone continues until the PBS_UP event is received.

Remarks

The AutoKeypadTonesMinimumDuration property functions only when the value of the AutoKeypadTones property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoKeypadTonesMinimumDuration, put_AutoKeypadTones


ITAutomatedPhoneControl::get_AutoStopRingOnOffHook

[This is preliminary documentation and subject to change.]

The get_AutoStopRingOnOffHook method retrieves the current value of the AutoStopRingOnOffHook property. When this feature is enabled, the phone going offhook results in the termination of any incoming ring produced on the phone (via a call to ITAutomatedPhoneControl::StopRinger).

HRESULT get_AutoStopRingOnOffHook(
  VARIANT_BOOL * pfEnabled
);

Parameters

pfEnabled
[out,retval] If VARIANT_TRUE, automatic incoming ring termination when the phone goes offhook is enabled. If VARIANT_FALSE, automatic incoming ring termination when the phone goes offhook is disabled.

Remarks

The AutoStopRingOnOffHook property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoStopRingOnOffHook property at any time. The reconfiguration takes effect the next time the phone goes offhook.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoStopRingOnOffHook, ITAutomatedPhoneControl::StopRinger, put_PhoneHandlingEnabled


ITAutomatedPhoneControl::get_AutoStopTonesOnOnHook

[This is preliminary documentation and subject to change.]

The get_AutoStopTonesOnOnHook method retrieves the current value of the AutoStopTonesOnOnHook property. When this feature is enabled, the phone going onhook results in the termination of any tone produced on the audio render device associated with the phone (via a call to ITAutomatedPhoneControl::StopTone).

HRESULT get_AutoStopTonesOnOnHook(
  VARIANT_BOOL * pfEnabled
);

Parameters

pfEnabled
[out,retval] If VARIANT_TRUE, automatic stop of tone generation upon onhook is enabled. If VARIANT_FALSE, automatic stop of tone generation upon onhook is disabled.

Remarks

The AutoStopTonesOnOnHook property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoStopTonesOnOnHook property at any time. The reconfiguration takes effect the next time the phone goes onhook.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoStopTonesOnOnHook, ITAutomatedPhoneControl::StopTone, put_PhoneHandlingEnabled


ITAutomatedPhoneControl::get_AutoVolumeControl

[This is preliminary documentation and subject to change.]

The get_AutoVolumeControl method retrieves the current value of the AutoVolumeControl property. When this feature is enabled, the phone's wave output volume is automatically adjusted whenever a volume button is pressed. The volume is adjusted by the amount indicated by the AutoVolumeControlStep property.

HRESULT get_AutoVolumeControl(
  VARIANT_BOOL * fEnabled
);

Parameters

fEnabled
[out,retval] VARIANT_TRUE indicates that automatic volume control is enabled. VARIANT_FALSE indicates that automatic volume control is disabled.

Remarks

You can set the AutoVolumeControl property at any time. The reconfiguration takes effect the next time a volume button is pressed.

The AutoVolumeControl property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoVolumeControl, put_AutoVolumeControlStep, put_PhoneHandlingEnabled


ITAutomatedPhoneControl::get_AutoVolumeControlRepeatDelay

[This is preliminary documentation and subject to change.]

The get_AutoVolumeControlRepeatDelay method retrieves the current value of the AutoVolumeControlRepeatDelay property. The property specifies the delay, in milliseconds (ms), before a volume button starts repeating when it is held down.

HRESULT get_AutoVolumeControlRepeatDelay(
  long * plDelay
);

Parameters

plDelay
[out,retval] Delay, in milliseconds, of the volume repeat delay. The default value is 500 ms.

Remarks

The AutoVolumeControlRepeatDelay property is valid only if the value of the AutoKeypadTones property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoVolumeControlRepeatDelay, put_AutoKeypadTones


ITAutomatedPhoneControl::get_AutoVolumeControlRepeatPeriod

[This is preliminary documentation and subject to change.]

The get_AutoVolumeControlRepeatPeriod method retrieves the current value of the AutoVolumeControlRepeatPeriod property. The property controls the period, in milliseconds (ms), of button repeats when a volume button is held down.

HRESULT get_AutoVolumeControlRepeatPeriod(
  long * plPeriod
);

Parameters

plPeriod
[out,retval] Period, in milliseconds (ms), of button repeats when a volume button is held down.

Remarks

The AutoVolumeControlRepeatDelay property is valid only if the value of the AutoKeypadTones property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoVolumeControlRepeatPeriod, put_AutoKeypadTones


ITAutomatedPhoneControl::get_AutoVolumeControlStep

[This is preliminary documentation and subject to change.]

The get_AutoVolumeControlStep method retrieves the current value of the AutoVolumeControlStep property. The property determines the amount that the phone volume is adjusted when the volume button is pressed.

HRESULT get_AutoVolumeControlStep(
  long * plStepSize
);

Parameters

plStepSize
[out,retval] Volume control step. The default value of the AutoVolumeControlStep property is 4096.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_AutoVolumeControlStep, put_AutoKeypadTones


ITAutomatedPhoneControl::get_PhoneHandlingEnabled

[This is preliminary documentation and subject to change.]

The get_PhoneHandlingEnabled method retrieves the current value of the PhoneHandlingEnabled property. Setting the property enables or disables all the automatic phone interaction features for this phone. Features include automated control of a phone's tones and rings, and automated call handling based on a phone's hookswitch state.

HRESULT get_PhoneHandlingEnabled(
  VARIANT_BOOL * pfEnabled
);

Parameters

pfEnabled
[out,retval] VARIANT_TRUE if automated phone handling is enabled, VARIANT_FALSE if automated phone handling is not enabled. The default value is VARIANT_FALSE.

Remarks

Typically, an application sets other properties on the ITAutomatedPhoneControl interface (to configure the details of the automatic phone interaction features required) before setting the PhoneHandlingEnabled property to VARIANT_TRUE. However, you can also adjust the properties after you call the put_PhoneHandlingEnabled method to enable the features.

When the phone is closed with a call to the ITPhone::Close method, the PhoneHandlingEnabled property is automatically reset to VARIANT_FALSE.

For a list of property methods that get and set the automatic phone interaction features, see ITAutomatedPhoneControl.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, put_PhoneHandlingEnabled, ITPhone::Close


ITAutomatedPhoneControl::get_Ringer

[This is preliminary documentation and subject to change.]

The get_Ringer method returns a Boolean value indicating whether the phone is currently performing an incoming ring that was initiated by the StartRinger method on this interface.

HRESULT get_Ringer(
  VARIANT_BOOL * pfRinging
);

Parameters

pfRinging
[out,retval] If VARIANT_TRUE, the phone is currently ringing.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, StartRinger


ITAutomatedPhoneControl::get_SelectedCalls

[This is preliminary documentation and subject to change.]

The get_SelectedCalls method retrieves a VARIANT containing a pointer to a collection object indicating which calls are currently selected on this phone. See ITAutomatedPhoneControl::SelectCall for more information.

This method is intended for applications written in Visual Basic, Java, or various scripting languages. C and C++ programmers should use the EnumerateSelectedCalls method instead.

HRESULT get_SelectedCalls(
  VARIANT * pVariant
);

Parameters

pVariant
[out,retval] Pointer to a VARIANT containing an ITCollection of IEnumCall interface pointers.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITAutomatedPhoneControl::SelectCall, EnumerateSelectedCalls, ITCollection, IEnumCall


ITAutomatedPhoneControl::get_Tone

[This is preliminary documentation and subject to change.]

The get_Tone method returns a PHONE_TONE enum value indicating the type of tone, if any, that the phone is currently playing. If no tone is currently being played, the PHONE_TONE value returned is PT_SILENCE. This method has knowledge only of tones initiated by the StartTone method on this interface.

HRESULT get_Tone(
  PHONE_TONE * pTone
);

Parameters

pTone
[out,retval] PHONE_TONE descriptor of tone being played.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, StartTone


ITAutomatedPhoneControl::put_AutoDialtone

[This is preliminary documentation and subject to change.]

The put_AutoDialtone method sets the value of the AutoDialtone property. The method enables or disables automatic dial tone response for this phone. When this feature is enabled, the phone going offhook results in a dial tone produced on the audio render device associated with the phone. No dial tone is produced if the phone was ringing when it went offhook.

HRESULT put_AutoDialtone(
  VARIANT_BOOL fEnabled
);

Parameters

fEnabled
[in] If VARIANT_TRUE, enables automatic dial tone. If VARIANT_FALSE, disables automatic dial tone. The default value is VARIANT_TRUE.

Remarks

The AutoDialtone property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoDialtone property at any time. The reconfiguration takes effect the next time the phone goes offhook.

All dial tone generation ceases when an invocation of ITAutomatedPhoneControl::SelectCall succeeds; dial tone generation remains suspended until the call is unselected.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITAutomatedPhoneControl::SelectCall, put_PhoneHandlingEnabled, get_AutoDialtone


ITAutomatedPhoneControl::put_AutoEndOfNumberTimeout

[This is preliminary documentation and subject to change.]

The put_AutoEndOfNumberTimeout method sets the value of the AutoEndOfNumberTimeout property. The property specifies how long to wait after a digit has been pressed before it is assumed that the entire number has been gathered.

HRESULT put_AutoEndOfNumberTimeout(
  long lTimeout
);

Parameters

lTimeout
[in] Timeout interval to wait, in milliseconds (ms). The default value is 3000 ms.

Remarks

A value of 0 turns off this timeout and bases the end-of-number detection solely on the user pressing the # or SEND buttons.

End-of-number-detection ceases (without a detection event) when an invocation of ITAutomatedPhoneControl::SelectCall succeeds, and detection remains suspended until the call is unselected.

The AutoEndOfNumberTimeout property controls only what happens after at least one keypad button has been pressed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITAutomatedPhoneControl::SelectCall, get_AutoEndOfNumberTimeout


ITAutomatedPhoneControl::put_AutoKeypadTones

[This is preliminary documentation and subject to change.]

The put_AutoKeypadTones method sets the AutoKeypadTones property for this phone. When this feature is enabled, a digit tone is automatically played whenever a keypad button is pressed.

HRESULT put_AutoKeypadTones(
  VARIANT_BOOL fEnabled
);

Parameters

fEnabled
[in] If VARIANT_TRUE, automatic phone keypad tone generation is enabled. If VARIANT_FALSE, keypad tone generation is disabled. The default value is VARIANT_TRUE.

Remarks

If the phone device reports a button press as PBS_DOWN, then the tone is played until the phone device reports a PBS_UP event or until the minimum duration has expired, whichever is longer. (The minimum duration is determined by the AutoKeypadTonesMinimumDuration property.)

Keypad tone generation will occur only when the phone is offhook. If another tone, such as ringback, is currently playing, the keypad tone will interrupt that tone and automatically restore it after the keypad tone has finished.

The AutoKeypadTones property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoKeypadTones property at any time. The reconfiguration takes effect the next time the phone keypad button is pressed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, get_AutoKeypadTones, put_PhoneHandlingEnabled, put_AutoKeypadTonesMinimumDuration


ITAutomatedPhoneControl::put_AutoKeypadTonesMinimumDuration

[This is preliminary documentation and subject to change.]

The put_AutoKeypadTonesMinimumDuration method sets the value of the AutoKeypadTonesMinimumDuration property. The property specifies how long to play keypad tones on PBS_DOWN.

HRESULT put_AutoKeypadTonesMinimumDuration(
  long lDuration
);

Parameters

lDuration
[in] Minimum duration of keypad tones, in milliseconds (ms). The default value is 250 ms. If the minimum duration elapses without a PBS_UP event, the keypad tone continues until the PBS_UP event is received.

Remarks

The AutoKeypadTonesMinimumDuration property is valid only if the value of the AutoKeypadTones property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, get_AutoKeypadTonesMinimumDuration, put_AutoKeypadTones


ITAutomatedPhoneControl::put_AutoStopRingOnOffHook

[This is preliminary documentation and subject to change.]

The put_AutoStopRingOnOffHook method sets the AutoStopRingOnOffHook property. When this feature is enabled, the phone going offhook results in the termination of any incoming ring produced on the phone (via a call to ITAutomatedPhoneControl::StopRinger).

HRESULT put_AutoStopRingOnOffHook(
  VARIANT_BOOL fEnabled
);

Parameters

fEnabled
[in] If VARIANT_TRUE, enables automatic incoming ring termination if the phone goes offhook. If VARIANT_FALSE, disables automatic incoming ring termination if the phone goes offhook. The default value is VARIANT_TRUE.

Remarks

The AutoStopRingOnOffHook property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoStopRingOnOffHook property at any time. The reconfiguration takes effect the next time the phone goes offhook.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, get_AutoStopRingOnOffHook, ITAutomatedPhoneControl::StopRinger, put_PhoneHandlingEnabled


ITAutomatedPhoneControl::put_AutoStopTonesOnOnHook

[This is preliminary documentation and subject to change.]

The put_AutoStopTonesOnOnHook method sets the AutoStopTonesOnOnHook property for this phone. When this feature is enabled, the phone going onhook results in the termination of any tone produced on the audio render device associated with the phone (via a call to ITAutomatedPhoneControl::StopTone).

HRESULT put_AutoStopTonesOnOnHook(
  VARIANT_BOOL fEnabled
);

Parameters

fEnabled
[in] If VARIANT_TRUE, enables automatic stop of tone generation if the phone goes onhook. If VARIANT_FALSE, disables automatic stop if the phone goes onhook. The default value is VARIANT_TRUE.

Remarks

The AutoStopTonesOnOnHook property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoStopTonesOnOnHook property at any time. The reconfiguration takes effect the next time the phone goes onhook.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITAutomatedPhoneControl::StopTone, get_AutoStopTonesOnOnHook, put_PhoneHandlingEnabled


ITAutomatedPhoneControl::put_AutoVolumeControl

[This is preliminary documentation and subject to change.]

The put_AutoVolumeControl method sets the AutoVolumeControl property for this phone. When this feature is enabled, the phone's wave output volume is automatically adjusted whenever a volume button is pressed. The volume is adjusted by the amount indicated by the AutoVolumeControlStep property.

HRESULT put_AutoVolumeControl(
  VARIANT_BOOL fEnabled
);

Parameters

fEnabled
[in] If VARIANT_TRUE, enables automatic volume control. If VARIANT_FALSE, disables automatic volume control. The default value is VARIANT_TRUE.

Remarks

The AutoVolumeControl property functions only when the value of the PhoneHandlingEnabled property is VARIANT_TRUE. You can set the AutoVolumeControl property at any time. The reconfiguration takes effect the next time a volume button is pressed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, get_AutoVolumeControl, put_AutoVolumeControlStep, put_PhoneHandlingEnabled


ITAutomatedPhoneControl::put_AutoVolumeControlRepeatDelay

[This is preliminary documentation and subject to change.]

The put_AutoVolumeControlRepeatDelay method sets the AutoVolumeControlRepeatDelay property. The property specifies the delay, in milliseconds (ms), before a volume button starts repeating when it is held down.

HRESULT put_AutoVolumeControlRepeatDelay(
  long lDelay
);

Parameters

lDelay
[in] Delay, in milliseconds (ms), before the volume button starts repeating. The default value is 500 ms.

Remarks

The AutoVolumeControlRepeatDelay property is valid only if the value of the AutoKeypadTones property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, get_AutoVolumeControlRepeatDelay, put_AutoKeypadTones


ITAutomatedPhoneControl::put_AutoVolumeControlRepeatPeriod

[This is preliminary documentation and subject to change.]

The put_AutoVolumeControlRepeatPeriod method sets the AutoVolumeControlRepeatPeriod property. The property controls the period, in milliseconds (ms), of button repeats when a volume button is held down.

HRESULT put_AutoVolumeControlRepeatPeriod(
  long lPeriod
);

Parameters

lPeriod
[in] Period, in milliseconds (ms), of button repeats when a volume button is held down. The default value is 100 ms.

Remarks

The AutoVolumeControlRepeatDelay property is valid only if the value of the AutoKeypadTones property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, get_AutoVolumeControlRepeatPeriod, put_AutoKeypadTones


ITAutomatedPhoneControl::put_AutoVolumeControlStep

[This is preliminary documentation and subject to change.]

The put_AutoVolumeControlStep method sets the AutoVolumeControlStep property. The property determines the amount that the phone volume is adjusted when the volume button is pressed.

HRESULT put_AutoVolumeControlStep(
  long lStepSize
);

Parameters

lStepSize
[in] Volume control step, in milliseconds. The default value of the AutoVolumeControlStep property is 4096.

Remarks

The AutoVolumeControlRepeatDelay property is valid only if the value of the AutoKeypadTones property is VARIANT_TRUE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, get_AutoVolumeControlStep, put_AutoKeypadTones


ITAutomatedPhoneControl::put_PhoneHandlingEnabled

[This is preliminary documentation and subject to change.]

The put_PhoneHandlingEnabled method sets the PhoneHandlingEnabled property. Setting the property enables or disables all the automatic phone interaction features for this phone. Features include automated control of a phone's tones and rings, and automated call handling based on a phone's hookswitch state.

HRESULT put_PhoneHandlingEnabled(
  VARIANT_BOOL fEnabled
);

Parameters

fEnabled
[in] If VARIANT_TRUE, phone handling is enabled. If VARIANT_FALSE, phone handling is disabled. The default value is VARIANT_FALSE.

Remarks

Typically, an application sets other properties on the ITAutomatedPhoneControl interface (to configure the details of the automatic phone interaction features required) before setting the PhoneHandlingEnabled property to VARIANT_TRUE. However, you can also adjust the properties after you call the put_PhoneHandlingEnabled method to enable the features.

When the phone is closed with a call to the ITPhone::Close method, the PhoneHandlingEnabled property is automatically reset to VARIANT_FALSE.

If you set the PhoneHandlingEnabled property to VARIANT_TRUE, and the phone doesn't have a ringer device, the ringing sound plays on the default audio device for the system; for example, on sound card speakers. For more information, see PHONECAPS_LONG.

For a list of property methods that get and set the automatic phone interaction features, see ITAutomatedPhoneControl.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAutomatedPhoneControl, ITPhone::Close, get_PhoneHandlingEnabled


ITBasicAudioTerminal

The ITBasicAudioTerminal interface provides methods that allow an application to control basic sound characteristics of terminal. These methods are taken from the IBasicAudio interface in DirectShow. Please check the index for the Platform SDK for additional information.

The ITBasicAudioTerminal interface can be obtained through QueryInterface from terminal objects that support this interface. For example, if the computer running Windows 2000 has a sound card, the addresses exposed by the H323 and IPCONF providers will enumerate, in their ITTerminalSupport interface, two static terminals that support the ITBasicAudioTerminal interface: one for "audio record" and one for "audio playback."

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITBasicAudioTerminal methods | Description
put_Volume | Sets the volume.
get_Volume | Gets the volume.
put_Balance | Sets the balance.
get_Balance | Gets the balance.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object


ITBasicAudioTerminal::get_Balance

The get_Balance method gets the balance. This method is not implemented for terminals shipped with TAPI 3.0.

HRESULT get_Balance(
  long *plBalance
);

Parameters

plBalance
[out, retval] Pointer to balance.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_NOTSUPPORTED | Terminal does not support balance operations.
E_NOTIMPL | Terminal's balance methods are not implemented.

Remarks

The balance property is a value between –10,000 and 10,000. A value of –10,000 indicates that the right speaker has been disabled and only the left speaker is receiving an audio signal. A value of 0 indicates that both speakers are receiving equivalent audio signals. A value of 10,000 indicates that the left speaker has been disabled and only the right speaker is receiving an audio signal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicAudioTerminal, put_Balance, Terminal Object


ITBasicAudioTerminal::get_Volume

The get_Volume method gets the volume.

HRESULT get_Volume(
  long *plVolume
);

Parameters

plVolume
[out, retval] Pointer to volume. The volume property is a value between 0 and FFFF, representing a set of logarithmic steps. Not all devices support as many distinguishable steps.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plVolume parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicAudioTerminal, put_Volume, Terminal Object


ITBasicAudioTerminal::put_Balance

The put_Balance method sets the balance. This method is not implemented for terminals shipped with TAPI 3.0.

HRESULT put_Balance(
  long lBalance
);

Parameters

lBalance
[in] Balance.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_NOTIMPL | Terminal's balance methods are not implemented.

Remarks

The balance property is a value between –10,000 and 10,000. A value of –10,000 indicates that the right speaker has been disabled and only the left speaker is receiving an audio signal. A value of 0 indicates that both speakers are receiving equivalent audio signals. A value of 10,000 indicates that the left speaker has been disabled and only the right speaker is receiving an audio signal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicAudioTerminal, get_Balance, Terminal Object


ITBasicAudioTerminal::put_Volume

The put_Volume method sets the volume.

HRESULT put_Volume(
  long lVolume
);

Parameters

lVolume
[in] The volume property is a value between 0 and FFFF, representing a set of logarithmic steps. Not all devices support as many distinguishable steps.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_NOTERMINALSELECTED | A terminal must be selected before the volume can be adjusted.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicAudioTerminal, get_Volume, Terminal Object


ITBasicCallControl

The ITBasicCallControl interface is used by the application to connect, answer, and perform basic telephony operations on a call object.

The ITBasicCallControl2 interface is an extension of the ITBasicCallControl interface. ITBasicCallControl2 supplies additional methods that allow an application to select a terminal onto a call.

Note to programmers familiar with TAPI 2.1: The general function of this interface is similar to the TAPI 2.1 line functions. For example, the lineAnswer function and the ITBasicCallControl::Answer method provide similar functionality.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITBasicCallControl methods | Description
Connect | Attempts to complete the connection of an outgoing call.
Answer | Answers an incoming call.
Disconnect | Disconnects the call.
Hold | Places or removes the call from the hold state.
HandoffDirect | Hands off the call to a specific application.
HandoffIndirect | Hands off the call to another application, specifying only the media type.
Conference | Starts a conference, with the current call included.
Transfer | Transfers the current call to the destination address.
BlindTransfer | Transfers the call to the indicated address.
SwapHold | Swaps the call (which is active) with the specified call on hold.
ParkDirect | Parks the call at a specified address.
ParkIndirect | Parks the call and returns the parked address.
Unpark | Gets the call parked at the specified address.
SetQOS | Sets the QOS service level for the call.
Pickup | Picks up a call alerting at the specified group identification.
Dial | Dials the given address.
Finish | Finishes the two-step process of transferring or adding the call to a conference.
RemoveFromConference | Removes the call from a conference.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Call Object, ITBasicCallControl2


ITBasicCallControl::Answer

The Answer method answers an incoming call. This method can succeed only if the call state is CS_OFFERING.

HRESULT Answer();

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Call state was not CS_OFFERING.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Answer Overview, Call Object, lineAnswer


ITBasicCallControl::BlindTransfer

The BlindTransfer method performs a blind or single-step transfer of the specified call to the specified destination address. The application must be the owner of the call. After a successful transfer, the call state transitions to CS_DISCONNECTED.

HRESULT BlindTransfer(
  BSTR pDestAddress
);

Parameters

pDestAddress
[in] Pointer to BSTR containing destination address for the transfer.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDestAddress is not a valid pointer.
E_FAIL | Blind transfer is not supported.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

The application must use SysAllocString to allocate memory for the pDestAddress parameter and use SysFreeString to free the memory when the variable is no longer needed.

In some cases, the application may need to use the address translation interfaces (ITAddressTranslation and ITAddressTranslationInfo) to obtain a pDestAddress string in the proper format.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Transfer Overview, ITAddressTranslation, ITAddressTranslationInfo, Call Object, lineBlindTransfer


ITBasicCallControl::Conference

The Conference method adds a consultation call to the conference in which the current call is a participant. If an associated ITCallHub object does not exist, it is created.

HRESULT Conference(
  ITBasicCallControl *pCall,
  VARIANT_BOOL fSync
);

Parameters

pCall
[in] Pointer to the ITBasicCallControl interface for the consultation call.
fSync
[in] Indicates whether the call should be conferenced synchronously (VARIANT_TRUE) or asynchronously (VARIANT_FALSE). See Connect for additional explanation.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCall parameter is not a valid pointer.
E_INVALIDARG | The pCall parameter does not point to a valid interface.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

The consultation call (pCall) is created by ITAddress::CreateCall. The connection is completed by calling the Finish method. Please see Create a Simple Conference for an example of using this method.

If the consultation call is not in the CONNECTED state when Conference is called, TAPI will use the destination address (as specified when the consultation call was first created via ITAddress::CreateCall) and try to connect at that time. If the original call had a NULL destination address, Conference will fail with E_INVALIDARG.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, ITAddress::CreateCall, Finish, Transfer, ITCallInfo::get_CallHub, Conference overview, Call Object, Create a Simple Conference


ITBasicCallControl::Connect

The Connect method attempts to complete the connection of an outgoing call.

HRESULT Connect(
  VARIANT_BOOL fSync
);

Parameters

fSync
[in] Boolean indicating whether connection is to be performed synchronously (VARIANT_TRUE) or asynchronously (VARIANT_FALSE).

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_INVALCALLSTATE | Call state must be CS_IDLE.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

If the call is asynchronous, the application will receive information about the call's progress through the ITCallNotificationEvent outgoing interface. The application must register the outgoing interface before calling Connect. Connect may return S_OK, but the actual connection may fail (and the application will be notified through the outgoing interface).

If the call is synchronous, this method will not return until the call is in the connected state or fails.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, ITAddress::CreateCall, Complete a Session, Call Object


ITBasicCallControl::Dial

The Dial method dials the specified address.

HRESULT Dial(
  BSTR pDestAddress
);

Parameters

pDestAddress
[in] Pointer to BSTR representation of address to be dialed. The format must conform to a standard dialable address.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pDestAddress parameter is not a valid pointer.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

The application must use SysAllocString to allocate memory for the pDestAddress parameter and use SysFreeString to free the memory when the variable is no longer needed.

In some cases, the application may need to use the address translation interfaces (ITAddressTranslation and ITAddressTranslationInfo) to obtain a pDestAddress string in the proper format.

The Dial method differs from ITAddress::CreateCall in that the call already exists. An example use is dialing an extension.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Call Object, ITAddress::CreateCall, lineDial, Dial overview, Dialable Addresses, ITAddressTranslation, ITAddressTranslationInfo


ITBasicCallControl::Disconnect

The Disconnect method disconnects the call. The call state will transition to CS_DISCONNECTED after the method completes successfully.

HRESULT Disconnect(
  DISCONNECT_CODE code
);

Parameters

code
[in] DISCONNECT_CODE indicating reason for call disconnection.

Return Values

Value | Meaning
S_OK | Method succeeded.
S_FALSE | The call state is CS_IDLE or a valid handle for the call could not be obtained by the TAPI 3.0 dll.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Terminate a Session Overview, Call Object, Drop overview, lineDrop, DISCONNECT_CODE


ITBasicCallControl::Finish

The Finish method is called on a consultation call to finish a conference or a transfer.

HRESULT Finish(
   FINISH_MODE finishMode
);

Parameters

finishMode
[in] A FINISH_MODE indicator of the type of call being finished, such as FM_ASCONFERENCE.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_INVALCALLSTATE | Call is not flagged as a transfer or a conference.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Conference, Transfer, FINISH_MODE, Create a Simple Conference code snippet, Conference overview, Forward overview, Transfer overview, Call Object


ITBasicCallControl::HandoffDirect

The HandoffDirect method hands off the call to another application. This indicates that the application no longer requires ownership of the call.

HRESULT HandoffDirect(
  BSTR pApplicationName
);

Parameters

pApplicationName
[in] Pointer to BSTR containing the specific application name to hand off call to. Can be full path name or executable name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pApplicationName parameter is not a valid pointer.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

If the receiving application has not opened the line for the media types involved in the call, the handoff will fail. If TAPI fails to hand off the call, TAPI will call Disconnect.

The application must use SysAllocString to allocate memory for the pApplicationName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Disconnect, Handoffs overview, Call Object, lineHandoff


ITBasicCallControl::HandoffIndirect

The HandoffIndirect method hands off the call to another application based on the media type of the call. If multiple applications have registered as able to handle the types involved, TAPI will hand off to the highest-priority application, which is usually the one that registered first.

This indicates that the application no longer requires ownership of the call.

HRESULT HandoffIndirect(
  long lMediaType
);

Parameters

lMediaType
[in] Media type to transfer to.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The lMediaType parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

If TAPI fails to hand off the call, TAPI will call Disconnect.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Handoffs overview, Call Object, lineHandoff, TAPIMEDIATYPE_ Constants


ITBasicCallControl::Hold

The Hold method places or removes the call from the hold.

HRESULT Hold(
  VARIANT_BOOL fHold
);

Parameters

fHold
[in] If fHold is VARIANT_TRUE and the method succeeds, the call state transitions to the CS_HOLD state. If fHold is VARIANT_FALSE, the call state transitions to CS_CONNECTED.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALCALLSTATE | The call associated with this interface no longer exists.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Hold overview, Call Object, lineHold


ITBasicCallControl::ParkDirect

The ParkDirect method parks the call at a specified address.

HRESULT ParkDirect(
  BSTR pParkAddress
);

Parameters

pParkAddress
[in] Pointer to BSTR containing the address where the call is to be parked.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pParkAddress parameter is not a valid pointer.
E_FAIL | Park is not supported.
E_INVALIDARG | The pParkAddress parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

With directed park, the application determines the address at which it wants to park the call. With ParkInDirect, the switch determines the address and provides this to the application. In either case, a parked call can be unparked by specifying this address.

The parked call enters the disconnected state after it has been successfully parked.

Some switches can remind the user after a call has been parked for some long amount of time. The application sees an offering call with a call reason set to reminder.

The application must use SysAllocString to allocate memory for the pParkAddress parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Park overview, Call Object, linePark


ITBasicCallControl::ParkIndirect

The ParkIndirect method parks the call and returns the parked address.

HRESULT ParkIndirect(
  BSTR *ppNonDirAddress
);

Parameters

ppNonDirAddress
[out, retval] Pointer to a BSTR representation of the address where the call was parked.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppNonDirAddress parameter is not a valid pointer.
E_FAIL | Park is not supported.
E_INVALIDARG | The ppNonDirAddress parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

With ParkDirect, the application determines the address at which it wants to park the call. With nondirected park, the switch determines the address and provides this to the application. In either case, a parked call can be unparked by specifying this address.

The parked call enters the disconnected state after it has been successfully parked.

Some switches can remind the user after a call has been parked for some long amount of time. The application sees an offering call with a call reason set to reminder.

The application must use SysFreeString to free the memory allocated for the ppNonDirAddress parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Park overview, Call Object, linePark


ITBasicCallControl::Pickup

The Pickup method picks up a call alerting at the specified group identification.

HRESULT Pickup(
  BSTR pGroupID
);

Parameters

pGroupID
[in] Pointer to a BSTR containing the group identifier to which the alerting station belongs.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Pickup did not succeed.
E_POINTER | The pGroupID parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

The application must use SysAllocString to allocate memory for the pGroupID parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Pickup overview, Call Object, linePickup


ITBasicCallControl::RemoveFromConference

The RemoveFromConference method removes the call from a conference if it is involved in one.

HRESULT RemoveFromConference();

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Call Object, lineRemoveFromConference, Conference overview


ITBasicCallControl::SetQOS

The SetQOS method sets the quality of service level for the call.

HRESULT SetQOS(
  long lMediaType,
  QOS_SERVICE_LEVEL ServiceLevel
);

Parameters

lMediaType
[in] Media type of call.
ServiceLevel
[in] QOS_SERVICE_LEVEL indicator of desired QOS level for call.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The lMediaType parameter is not a valid media type.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Call Object, QOS_SERVICE_LEVEL


ITBasicCallControl::SwapHold

The SwapHold method swaps the call (which is active) with the specified call on hold.

Swapping the active call with the call on consultation hold allows the application to toggle between these two calls. This is typical in call waiting.

HRESULT SwapHold(
  ITBasicCallControl *pCall
);

Parameters

pCall
[in] Call, currently on hold, that is to be made active.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | This operation is not supported.
E_POINTER | The pCall parameter is not a valid pointer.
E_INVALIDARG | The pCall parameter does not describe a currently existing call.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_OPERATIONFAILED | The operation failed.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Call Object, lineSwapHold


ITBasicCallControl::Transfer

The Transfer method transfers the current call to the destination address.

HRESULT Transfer(
  ITBasicCallControl *pCall,
  VARIANT_BOOL fSync
);

Parameters

pCall
[in] Pointer to ITBasicCallControl interface of consultation call created for the transfer.
fSync
[in] Indicates whether the method should be completed synchronously (VARIANT_TRUE) or asynchronously (VARIANT_FALSE).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pCall parameter does not point to a valid call.
E_FAIL | Transfers not supported.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some service providers do not support this operation while streaming is active. The application may need to call ITStream::StopStream or ITSubStream::StopSubStream prior to the operation and ITStream::StartStream or ITSubStream::StartSubStream following completion of the operation.

Call transfer involves setting up a consultation call in preparation for the transfer. pCall is the ITBasicCallControl pointer returned by ITAddress::CreateCall following the creation of a consultation call. ITBasicCallControl::Finish (FM_ASTRANSFER) completes the transfer.

If the consultation call is not in the CONNECTED state when Transfer is called, TAPI will use the destination address (as specified when the consultation call was first created via ITAddress::CreateCall) and try to connect at that time. If the original call had a NULL destination address, Transfer will fail with E_INVALIDARG.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, Conference, Finish, ITAddress::CreateCall, Transfer Overview, Call Object


ITBasicCallControl::Unpark

The Unpark method gets the call from park.

HRESULT Unpark(
);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | The park operation is not supported.
TAPI_E_INVALCALLSTATE | Call state must be CS_IDLE.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

In order to unpark a call, CreateCall must be called using as the destination address the current parked location of the call. For example:

pAddress->CreateCall( bstrAddressToCall,
                      dwAddressType,
                      &pBasicCall ;
// Select appropriate terminals for call, and then call:
pBasicCall ->Unpark();

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl, ITAddress::CreateCall, ParkDirect, ParkIndirect, Park overview, Call Object, lineUnpark


ITBasicCallControl2

[This is preliminary documentation and subject to change.]

The ITBasicCallControl2 interface is an extension of the ITBasicCallControl interface. ITBasicCallControl2 supplies additional methods that allow an application to select a terminal onto a call.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITBasicCallControl2 methods | Description
RequestTerminal | Gets a suitable terminal, given the class, media, and direction required.
SelectTerminalOnCall | Selects a terminal onto the call.
UnselectTerminalOnCall | Unselects a terminal from the call.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl


ITBasicCallControl2::RequestTerminal

[This is preliminary documentation and subject to change.]

The RequestTerminal method gets a suitable terminal, given the class, media, and direction required.

HRESULT RequestTerminal(
  BSTR bstrTerminalClassGUID,
  long lMediaType,
  TERMINAL_DIRECTION Direction,
  ITTerminal ** ppTerminal
);

Parameters

bstrTerminalClassGUID
[in] The terminal class required for the call.
lMediaType
[in] Bitwise ORed list of media types required for the call.
Direction
[in] The TERMINAL_DIRECTION descriptor for the terminal.
ppTerminal
[out,retval] Pointer to ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl2, ITTerminal


ITBasicCallControl2::SelectTerminalOnCall

[This is preliminary documentation and subject to change.]

The SelectTerminalOnCall method selects the terminal onto the call.

HRESULT SelectTerminalOnCall(
  ITTerminal * pTerminal
);

Parameters

pTerminal
[in] Pointer to the ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl2, ITTerminal


ITBasicCallControl2::UnselectTerminalOnCall

[This is preliminary documentation and subject to change.]

The UnselectTerminalOnCall method unselects a terminal from the call.

HRESULT UnselectTerminalOnCall(
  ITTerminal * pTerminal
);

Parameters

pTerminal
[in] Pointer to ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITBasicCallControl2, ITTerminal


ITCallHub

The ITCallHub interface provides methods to retrieve information concerning a CallHub object.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallHub methods | Description
Clear | Attempts to remove all calls and participants from Call Hub.
EnumerateCalls | Enumerates calls currently associated with the call hub.
get_Calls | Creates a collection of calls associated with the current call hub. This method is provided for Automation client applications, such as those written in Microsoft Visual Basic.
get_NumCalls | Gets the number of calls currently in the CallHub.
get_State | Gets the current state of the CallHub.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

CallHub Object


ITCallHub::Clear

The Clear method attempts to remove all calls and participants from CallHub. The application may not have the privileges required to disconnect every call.

HRESULT Clear();

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHub, CallHub Object


ITCallHub::EnumerateCalls

The EnumerateCalls method enumerates calls currently associated with the call hub. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Calls method.

HRESULT EnumerateCalls(
  IEnumCall **ppEnumCall
);

Parameters

ppEnumCall
[out, retval] Pointer to IEnumCall interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to create the enumerator.
E_POINTER | The ppEnumCall parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHub, CallHub Object


ITCallHub::get_NumCalls

The get_NumCalls method gets the number of calls currently in the CallHub.

HRESULT get_NumCalls(
  long *plCalls
);

Parameters

plCalls
[out, retval] Total number of calls in the CallHub.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCalls parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHub, CallHub Object


ITCallHub::get_Calls

The get_Calls method creates a collection of calls associated with the current call hub. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateCalls method.

HRESULT get_Calls(
  VARIANT *pCalls
);

Parameters

pCalls
[out, retval] Pointer to a VARIANT containing an ITCollection of ITCallInfo interface pointers (call objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pCalls parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHub, CallHub Object, ITCollection, ITCallInfo


ITCallHub::get_State

The get_State method gets the current state of the CallHub.

HRESULT get_State(
  CALLHUB_STATE *pState
);

Parameters

pState
[out, retval] Pointer to CALLHUB_STATE indicator of state.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pState parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHub, CallHub Object, CALLHUB_STATE


ITCallHubEvent

The ITCallHubEvent interface contains methods that retrieve the description of CallHub events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_CALLHUB, the method's pEvent parameter is an IDispatch pointer for the ITCallHubEvent interface. The methods of this interface can be used to retrieve information concerning the CallHub change that has occurred.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_CALLHUB event to enable reception of CallHub events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallHubEvent methods | Description
get_Event | Gets a CALLHUB_EVENT descriptor of the event.
get_CallHub | Gets a pointer to the ITCallHub interface.
get_Call | Gets a pointer to the ITCallInfo interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITCallHub, ITCallInfo, CALLHUB_EVENT, CallHub Object, Register Events code snippet


ITCallHubEvent::get_Call

The get_Call method returns a pointer to the ITCallInfo interface of the call on which the event occurred.

HRESULT get_Call(
  ITCallInfo **ppCall
);

Parameters

ppCall
[out, retval] ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCallt parameter is not a valid pointer.

Remarks

This method may return a NULL if the event is not associated with a call.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHubEvent, CallHub Object


ITCallHubEvent::get_CallHub

The get_CallHub method returns a pointer to the ITCallHub interface on which the event occurred.

HRESULT get_CallHub(
  ITCallHub **ppCallHub
);

Parameters

ppCallHub
[out, retval] Pointer to ITCallHub interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCallHubState parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHubEvent, CallHub Object


ITCallHubEvent::get_Event

The get_Event method returns a pointer to a CALLHUB_EVENT enum description of the event that occurred.

HRESULT get_Event(
  CALLHUB_EVENT *pEvent
);

Parameters

pEvent
[out, retval] Pointer to a CALLHUB_EVENT enum description of the event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pEvent parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallHubEvent, CallHub Object, CALLHUB_EVENT


ITCallInfo

The ITCallInfo interface gets and sets a variety of information concerning a Call object.

The ITCallInfo2 interface is an extension of the ITCallInfo interface. ITCallInfo2 provides additional methods that allow an application to set event filtering on a per-call basis.

For a table showing the relationships between TAPI 2 functions and RC1 ITCallInfo methods, see ITCallInfo TAPI 2 to TAPI 3 Cross-Reference.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallInfo methods | Description
get_Address | Gets a pointer to the ITAddress interface of the Address object.
get_CallState | Gets a pointer to the current call state, such as CS_IDLE.
get_Privilege | Gets the call privilege of the application for the current call, such as CP_MONITOR.
get_CallHub | Gets a pointer to the ITCallHub interface of the CallHub object.
get_CallInfoLong | Gets call information items described by a long, such as the bearer mode.
put_CallInfoLong | Sets call information items described by a long, such as the bearer mode.
get_CallInfoString | Gets call information items described by a string, such as the displayable address.
put_CallInfoString | Sets call information items described by a string, such as the displayable address.
get_CallInfoBuffer | Gets call information items that require a buffer, such as user-user information. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the ITCallInfo::GetCallInfoBuffer method.
put_CallInfoBuffer | Sets call information items that require a buffer, such as user-user information. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the ITCallInfo::SetCallInfoBuffer method.
GetCallInfoBuffer | Gets call information items that require a buffer, such as user-user information.
SetCallInfoBuffer | Sets call information items that require a buffer, such as user-user information.
ReleaseUserUserInfo | Releases the UUI buffer for this call.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object, lineGetCallInfo, lineGetCallStatus, LINECALLINFO, LINECALLSTATUS, ITCallInfo2


ITCallInfo::GetCallInfoBuffer

The GetCallInfoBuffer method gets call information items that require a buffer, such as user-user information. Automation client applications, such as those written in Visual Basic, must use the ITCallInfo::get_CallInfoBuffer method.

HRESULT GetCallInfoBuffer(
  CALLINFO_BUFFER CallInfoBuffer,
  DWORD * pdwSize,
  BYTE ** ppCallInfoBuffer
);

Parameters

CallInfoBuffer
[in] CALLINFO_BUFFER indicator of information type needed, such as CIB_USERUSERINFO.
pdwSize
[out] Size of buffer returned in bytes.
ppCallInfoBuffer
[out] Pointer to buffer containing the needed call information.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pdwSize or ppCallInfoBuffer parameter is not a valid pointer.
E_INVALIDARG | The CallInfoBuffer parameter is not a valid value.
TAPI_E_INVALCALLSTATE | The current call state is not valid for this operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, SetCallInfoBuffer, get_CallInfoBuffer, put_CallInfoBuffer, CALLINFO_BUFFER


ITCallInfo::SetCallInfoBuffer

The SetCallInfoBuffer method sets call information items that require a buffer, such as user-user information. Automation client applications, such as those written in Visual Basic, must use the ITCallInfo::put_CallInfoBuffer method.

HRESULT SetCallInfoBuffer(
  CALLINFO_BUFFER CallInfoBuffer,
  DWORD dwSize,
  BYTE *pCallInfoBuffer
);

Parameters

CallInfoBuffer
[in] CALLINFO_BUFFER indicator of information type needed, such as CIB_USERUSERINFO.
dwSize
[in] Size of pCallInfoBuffer.
pCallInfoBuffer
[in] Pointer to call information buffer.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCallInfoBuffer parameter is not a valid pointer.
E_INVALIDARG | The CallInfoBuffer parameter is not a valid value.
TAPI_E_INVALCALLSTATE | The current call state is not valid for this operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, GetCallInfoBuffer, get_CallInfoBuffer, put_CallInfoBuffer, CALLINFO_BUFFER


ITCallInfo::get_CallInfoBuffer

The get_CallInfoBuffer method gets call information items which require a buffer, such as user-user information. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the ITCallInfo::GetCallInfoBuffer method.

HRESULT get_CallInfoBuffer(
  CALLINFO_BUFFER CallInfoBuffer,
  VARIANT *ppCallInfoBuffer
);

Parameters

CallInfoBuffer
[in] CALLINFO_BUFFER indicator of information type needed, such as CIB_USERUSERINFO.
ppCallInfoBuffer
[out] Pointer to VARIANT representation of call information buffer. The application must call the CoTaskMemFree function to free the memory allocated for this parameter.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCallInfoBuffer parameter is not a valid pointer.
E_INVALIDARG | The CallInfoBuffer parameter is not a valid value.
TAPI_E_INVALCALLSTATE | Call state must not be CS_IDLE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, GetCallInfoBuffer, SetCallInfoBuffer, put_CallInfoBuffer, CALLINFO_BUFFER


ITCallInfo::get_CallInfoLong

The get_CallInfoLong method gets call information items described by a long, such as the bearer mode.

HRESULT get_CallInfoLong(
  CALLINFO_LONG CallInfoLong,
  long *plCallInfoLongVal
);

Parameters

CallInfoLong
[in] CALLINFO_LONG indicator of information type needed, such as CIL_BEARERMODE.
plCallInfoLongVal
[out] Pointer to value returned.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCallInfoLongVal parameter is not a valid pointer.
E_INVALIDARG | The CallInfoLong parameter is not a valid value.
TAPI_E_INVALCALLSTATE | Call state must not be CS_IDLE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, put_CallInfoLong, CALLINFO_LONG


ITCallInfo::get_CallInfoString

The get_CallInfoString method gets call information items described by a string, such as the displayable address.

HRESULT get_CallInfoString(
  CALLINFO_STRING CallInfoString,
  BSTR *ppCallInfoString
);

Parameters

CallInfoString
[in] CALLINFO_STRING indicator of information type needed, such as CIS_DISPLAYABLEADDRESS.
ppCallInfoString
[out] Pointer to BSTR representation of needed string.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCallInfoString parameter is not a valid pointer.
E_INVALIDARG | The CallInfoString parameter is not a valid value.
TAPI_E_INVALCALLSTATE | Call state must not be CS_IDLE.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCallInfoString parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, put_CallInfoString, CALLINFO_STRING


ITCallInfo::put_CallInfoBuffer

The put_CallInfoBuffer method sets call information items which require a buffer, such as user-user information. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the ITCallInfo::SetCallInfoBuffer method.

HRESULT put_CallInfoBuffer(
  CALLINFO_BUFFER CallInfoBuffer,
  VARIANT pCallInfoBuffer
);

Parameters

CallInfoBuffer
[in] CALLINFO_BUFFER indicator of information type, such as CIB_USERUSERINFO.
pCallInfoBuffer
[in] Pointer to VARIANT representation of call information buffer.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_INVALIDARG | The CallInfoBuffer parameter is not a valid value.
TAPI_E_INVALCALLSTATE | Call state must be CS_IDLE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, GetCallInfoBuffer, SetCallInfoBuffer, get_CallInfoBuffer, CALLINFO_BUFFER


ITCallInfo::put_CallInfoLong

The put_CallInfoLong method sets call information items described by a long, such as the bearer mode.

HRESULT put_CallInfoLong(
  CALLINFO_LONG CallInfoLong,
  long lCallInfoLongVal
);

Parameters

CallInfoLong
[in] CALLINFO_LONG indicator of information type needed, such as CIL_BEARERMODE.
lCallInfoLongVal
[in] Pointer to new value.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_INVALIDARG | The CallInfoLong parameter is not a valid value.
TAPI_E_INVALCALLSTATE | Call state must be CS_IDLE.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, get_CallInfoLong, CALLINFO_LONG


ITCallInfo::put_CallInfoString

The put_CallInfoString method sets call information items described by a string, such as the displayable address.

HRESULT put_CallInfoString(
  CALLINFO_STRING CallInfoString,
  BSTR pCallInfoString
);

Parameters

CallInfoString
[in] CALLINFO_STRING indicator of information type, such as CIS_DISPLAYABLEADDRESS.
pCallInfoString
[in] Pointer to BSTR representation of string.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_INVALIDARG | The CallInfoString parameter is not a valid value.
TAPI_E_INVALCALLSTATE | Call state must be CS_IDLE.

Remarks

The application must use SysAllocString to allocate memory for the pCallInfoString parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, get_CallInfoString, CALLINFO_STRING


ITCallInfo::get_Address

The get_Address method gets a pointer to the ITAddress interface of the Address object.

HRESULT get_Address(
  ITAddress **ppAddress
);

Parameters

ppAddress
[out, retval] Pointer to ITAddress interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, ITAddress, Address object, Call Object


ITCallInfo::get_CallHub

The get_CallHub method gets a pointer to the ITCallHub interface of the CallHub object.

HRESULT get_CallHub(
  ITCallHub **ppCallHub
);

Parameters

ppCallHub
[out, retval] Pointer to ITCallHub interface of the CallHub object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_PENDING | Call hub not yet available.
E_POINTER | The ppCallHub parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

On some service providers, the call hub is not available until after the call is made.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, ITCallHub, CallHub object, Call Object


ITCallInfo::get_CallState

The get_CallState method gets a pointer to the current call state, such as CS_IDLE.

HRESULT get_CallState(
  CALL_STATE *pCallState
);

Parameters

pCallState
[out, retval] Pointer to variable containing current CALL_STATE type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pCallState parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, CALL_STATE, Call Object, CALL_STATE

TAPI 2.1 Cross-Reference: LINECALLSTATUS, ITCallInfo

TAPI 2.1 Cross-Reference: dwMediaMode member of LINECALLINFO structure, Call Object


ITCallInfo::get_Privilege

The get_Privilege method gets the call privilege of the application for the current call, such as CP_MONITOR.

HRESULT get_Privilege(
 CALL_PRIVILEGE *pPrivilege
);

Parameters

pPrivilege
[out, retval] Pointer to CALL_PRIVILEGE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pPrivilege parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object, CALL_PRIVILEGE

TAPI 2.1 Cross-Reference: LINECALLSTATUS


ITCallInfo::ReleaseUserUserInfo

The ReleaseUserUserInfo method informs the service provider that the application has processed the user-user information obtained from the ITCallInfo::GetCallInfoBuffer method, called with the CIB_USERUSERINFO member of CALLINFO_BUFFER, and subsequently received user-user information can now be written.

HRESULT ReleaseUserUserInfo( );

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo, Call Object


ITCallInfo2

[This is preliminary documentation and subject to change.]

The ITCallInfo2 interface is an extension of the ITCallInfo interface. ITCallInfo2 provides additional methods that allow an application to set event filtering on a per-call basis.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallInfo2 methods | Description
get_EventFilter | Gets the current status of a filtering for a given event.
put_EventFilter | Sets filtering for a given event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo


ITCallInfo2::get_EventFilter

[This is preliminary documentation and subject to change.]

The get_EventFilter method gets the event filter information applicable to this call.

HRESULT get_EventFilter(
  TAPI_EVENT TapiEvent,
  long lSubEvent,
  VARIANT_BOOL * pEnable
);

Parameters

TapiEvent
[in] The TAPI_EVENT descriptor of event type information being checked.
lSubEvent
[in] Subevent descriptor.
pEnable
[out,retval] VARIANT_TRUE if notifications are being sent on this event type for this call.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo2


ITCallInfo2::put_EventFilter

[This is preliminary documentation and subject to change.]

The put_EventFilter method sets an event filter for the current call.

HRESULT put_EventFilter(
  TAPI_EVENT TapiEvent,
  long lSubEvent,
  VARIANT_BOOL bEnable
);

Parameters

TapiEvent
[in] The TAPI_EVENT descriptor of the event type.
lSubEvent
[in] Subevent descriptor.
bEnable
[in] VARIANT_TRUE if application requires notification of this event type. VARIANT_FALSE indicates the application does not require notifications for this event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfo2


ITCallInfoChangeEvent

The ITCallInfoChangeEvent interface contains methods that retrieve the description of call information change events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_CALLINFOCHANGE, the method's pEvent parameter is an IDispatch pointer for the ITCallInfoChangeEvent interface. The methods of this interface can be used to retrieve information concerning the call information that has changed.

The ITCallInfoChangeEvent is an outgoing interface. This interface is registered with the TAPI object to get all information about calls. An application must have called the ITTAPI::RegisterCallNotifications method on the TAPI object before registering this interface. If not, the call to Advise will fail. This interface cannot be unregistered — Unadvise will always fail.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_CALLINFOCHANGE event to enable reception of call information change events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallInfoChangeEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface.
get_Cause | Gets a CALLINFOCHANGE_CAUSE descriptor of the change.
get_CallbackInstance | Gets the callback instance associated with the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object, ITTAPIEventNotification::Event, TAPI_EVENT, ITCallInfo, ITTAPI::RegisterCallNotifications, Register Events code snippet


ITCallInfoChangeEvent::get_Call

The get_Call method returns the ITCallInfo interface on which call information has changed.

HRESULT get_Call(
  ITCallInfo **ppCall
);

Parameters

ppCall
[out, retval] Pointer to ITCallInfo interface on which information has changed.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCall parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfoChangeEvent, Call Object


ITCallInfoChangeEvent::get_CallbackInstance

The get_CallbackInstance method gets a pointer to the callback instance associated with this event.

HRESULT get_CallbackInstance(
  long *plCallbackInstance
);

Parameters

plCallbackInstance
[out, retval] Pointer to callback instance returned by ITTAPI::RegisterCallNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCallbackInstance parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfoChangeEvent, ITTAPI::RegisterCallNotifications, Call Object


ITCallInfoChangeEvent::get_Cause

The get_Cause method gets a CALLINFOCHANGE_CAUSE description of the change.

HRESULT get_Cause(
  CALLINFOCHANGE_CAUSE *pCIC
);

Parameters

pCIC
[out, retval] Pointer to CALLINFOCHANGE_CAUSE description of the call event that has occurred.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCIC parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallInfoChangeEvent, Call Object, CALLINFOCHANGE_CAUSE


ITCallingCard

The ITCallingCard interface provides methods to retrieve information concerning telephony calling cards.

An ITCallingCard interface pointer can be obtained using ITAddressTranslation::get_CallingCards or ITAddressTranslation::EnumerateCallingCards.

TAPI 2.1 Cross-Reference: The information obtainable using this interface parallels that contained in the LINECARDENTRY structure. The lineGetTranslateCaps function returns a LINETRANSLATECAPS structure. The dwCardListOffset member of this structure points to a list of LINECARDENTRY structures.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallingCard methods | Description
get_PermanentCardID | Gets the permanent calling card identifier.
get_NumberOfDigits | Gets the number of digits in the existing card number.
get_Options | Gets the translation options for this address and card.
get_CardName | Gets the friendly name for the calling card.
get_SameAreaDialingRule | Gets the dialing rules for calls within the same area code.
get_LongDistanceDialingRule | Gets the long distance dialing rules for this calling card.
get_InternationalDialingRule | Gets the international dialing rules for this calling card.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslation::get_CallingCards, ITAddressTranslation::EnumerateCallingCards, LINECARDENTRY, lineGetTranslateCaps, LINETRANSLATECAPS


ITCallingCard::get_CardName

The get_CardName method gets the friendly name for the calling card.

HRESULT get_CardName(
  BSTR *ppCardName
);

Parameters

ppCardName
[out, retval] Pointer to BSTR containing a displayable name for the calling card.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCardName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCardName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallingCard


ITCallingCard::get_InternationalDialingRule

The get_InternationalDialingRule method gets the international dialing rules for this calling card.

HRESULT get_InternationalDialingRule(
  BSTR *ppRule
);

Parameters

ppRule
[out, retval] Pointer to BSTR representation of international dialing rules.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppRule parameter is not a valid pointer.
E_POINTER | The ppRule parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppRule parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallingCard


ITCallingCard::get_LongDistanceDialingRule

The get_LongDistanceDialingRule method gets the long distance dialing rules for this calling card.

HRESULT get_LongDistanceDialingRule(
  BSTR *ppRule
);

Parameters

ppRule
[out, retval] Pointer to BSTR representation of long distance dialing rules.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppRule parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppRule parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallingCard


ITCallingCard::get_NumberOfDigits

The get_NumberOfDigits method gets the number of digits in the existing card number.

HRESULT get_NumberOfDigits(
  long *plDigits
);

Parameters

plDigits
[out, retval] Pointer to number of digits in the card number.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The plDigits parameter is not a valid pointer.
E_POINTER | The plDigits parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The card number itself is not returned for security reasons. The application can use this information to insert filler bytes into a text control in "password" mode to show that a number exists.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallingCard


ITCallingCard::get_Options

The get_Options method gets the translation options for this address and card.

HRESULT get_Options(
  long *plOptions
);

Parameters

plOptions
[out, retval] Pointer to LINETRANSLATEOPTION flags.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plOptions parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallingCard


ITCallingCard::get_PermanentCardID

The get_PermanentCardID method gets the permanent identifier that identifies the card.

HRESULT get_PermanentCardID(
  long *plCardID
);

Parameters

plCardID
[out, retval] Pointer to calling card identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The plCardID parameter is not valid.
E_POINTER | The plCardID parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallingCard


ITCallingCard::get_SameAreaDialingRule

The get_SameAreaDialingRule method gets the dialing rules for calls within the same area code.

HRESULT get_SameAreaDialingRule(
  BSTR *ppRule
);

Parameters

ppRule
[out, retval] Pointer to BSTR representation of local area dialing rules.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppRule parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppRule parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallingCard


ITCallMediaEvent

The ITCallMediaEvent interface contains methods that retrieve the description of media events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_CALLMEDIA, the method's pEvent parameter is an IDispatch pointer for the ITCallMediaEvent interface. The methods of this interface can be used to retrieve information concerning the call media event that has occurred.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_CALLMEDIA event to enable reception of call media events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallMediaEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface.
get_Event | Gets the CALL_MEDIA_EVENT descriptor of an event.
get_Error | Gets the error associated with the media event, if any.
get_Terminal | Gets a pointer to the ITTerminal interface.
get_Stream | Gets a pointer to the ITStream interface.
get_Cause | Gets the CALL_MEDIA_EVENT_CAUSE for the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITCallInfo, CALL_MEDIA_EVENT, CALLHUB_EVENT, CALL_MEDIA_EVENT_CAUSE, Call Object, Register Events code snippet


ITCallMediaEvent::get_Call

The get_Call method gets an ITCallInfo interface pointer for the call object associated with this event.

HRESULT get_Call(
  ITCallInfo **ppCallInfo
);

Parameters

ppCallInfo
[out, retval] Pointer to ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCallInfo parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallMediaEvent, Call Object


ITCallMediaEvent::get_Cause

The get_Cause method gets the cause of the call media event, such as a timeout on the renderer device.

HRESULT get_Cause(
  CALL_MEDIA_EVENT_CAUSE *pCause
);

Parameters

pCause
[out, retval] Pointer to CALL_MEDIA_EVENT_CAUSE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCause parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object, CALL_MEDIA_EVENT_CAUSE


ITCallMediaEvent::get_Error

The get_Error method gets the error associated with the media event, if any.

HRESULT get_Error(
  HRESULT *phrError
);

Parameters

phrError
[out, retval] Pointer to error.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The phrError parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallMediaEvent, Call Object


ITCallMediaEvent::get_Event

The get_Event method gets the call media event indicator.

HRESULT get_Event(
  CALL_MEDIA_EVENT *pCallMediaEvent
);

Parameters

pCallMediaEvent
[out, retval] Pointer to CALL_MEDIA_EVENT indicator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCallMediaEvent parameter is not a valid pointer.

Remarks

Call media events are a crucial indicator of whether certain operations can be performed. For example, when IVideoWindow is exposed on the Terminal object, until the CME_STREAM_ACTIVE is received only the put_Visible method will succeed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallMediaEvent, Call Object, CALL_MEDIA_EVENT


ITCallMediaEvent::get_Stream

The get_Stream method gets a pointer to the ITStream interface associated with the call media event.

HRESULT get_Stream(
  ITStream **ppStream
);

Parameters

ppStream
[out, retval] Pointer to ITStream interface pointer.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppStream parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallMediaEvent, Call Object


ITCallMediaEvent::get_Terminal

The get_Terminal method gets the terminal associated with the event.

HRESULT get_Terminal(
  ITTerminal **ppTerminal
);

Parameters

ppTerminal
[out, retval] Pointer to ITTerminal interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppTerminal parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallMediaEvent, Call Object


ITCallNotificationEvent

The ITCallNotificationEvent interface contains methods that retrieve the description of call notification events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_CALLNOTIFICATION, the method's pEvent parameter is an IDispatch pointer for the ITCallNotificationEvent interface. The methods of this interface can be used to retrieve information concerning the call notification event that has occurred.

This outgoing interface is registered with the TAPI object to get all information about calls. An application must call the ITTAPI::RegisterCallNotifications method on the TAPI object before registering this interface.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_CALLNOTIFICATION event to enable reception of call notification events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallNotificationEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface.
get_Event | Gets a CALL_NOTIFICATION_EVENT descriptor of the event.
get_CallbackInstance | Gets the callback instance associated with the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI::RegisterCallNotifications, ITTAPIEventNotification::Event, TAPI_EVENT, Call Object, Register Events code snippet


ITCallNotificationEvent::get_Call

The get_Call method returns the ITCallInfo interface on which a call event has occurred.

HRESULT get_Call(
  ITCallInfo **ppCall
);

Parameters

ppCall
[out, retval] Pointer to ITCallInfo interface on which call event has occurred.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCall parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallNotificationEvent, Call Object


ITCallNotificationEvent::get_CallbackInstance

The get_CallbackInstance method gets a pointer to the callback instance associated with this event.

HRESULT get_CallbackInstance(
  long *plCallbackInstance
);

Parameters

plCallbackInstance
[out, retval] Pointer to callback instance returned by ITTAPI::RegisterCallNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCallbackInstance parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallNotificationEvent, ITTAPI::RegisterCallNotifications, Call Object


ITCallNotificationEvent::get_Event

The get_Event method returns a CALL_NOTIFICATION_EVENT description of whether the application owns or is monitoring the call on which the event has occurred.

HRESULT get_Event(
  CALL_NOTIFICATION_EVENT *pCallNotificationEvent
);

Parameters

pCallNotificationEvent
[out, retval] Pointer to the CALL_NOTIFICATION_EVENT description of the application's privilege on the call returned by ITCallNotificationEvent::get_Call.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCallNotificationEvent parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallNotificationEvent, CALL_NOTIFICATION_EVENT, Call Object


ITCallStateEvent

The ITCallStateEvent interface contains methods that retrieve the description of call state events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_CALLSTATE, the method's pEvent parameter is an IDispatch pointer for the ITCallStateEvent interface. The methods of this interface can be used to retrieve information concerning the change that has occurred in the call state.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_CALLSTATE event to enable reception of call state events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCallStateEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface.
get_State | Gets a CALL_STATE descriptor of the event.
get_Cause | Gets a CALL_STATE_EVENT_CAUSE descriptor of the event.
get_CallbackInstance | Gets the callback instance associated with the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Call Object, ITTAPIEventNotification::Event, TAPI_EVENT, ITTAPI::put_EventFilter, CALL_STATE_EVENT_CAUSE, CALL_STATE, Register Events code snippet


ITCallStateEvent::get_Call

The get_Call method gets a pointer to the call information interface for the call on which the event has occurred.

HRESULT get_Call(
  ITCallInfo **ppCallInfo
);

Parameters

ppCallInfo
[out, retval] Pointer to ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCallInfo parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallStateEvent, Call Object


ITCallStateEvent::get_CallbackInstance

The get_CallbackInstance method gets a pointer to the callback instance associated with this event.

HRESULT get_CallbackInstance(
  long *plCallbackInstance
);

Parameters

plCallbackInstance
[out, retval] Pointer to callback instance returned by ITTAPI::RegisterCallNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCallbackInstance parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallStateEvent, ITTAPI::RegisterCallNotifications, Call Object


ITCallStateEvent::get_Cause

The get_Cause method gets the cause associated with this event.

HRESULT get_Cause(
  CALL_STATE_EVENT_CAUSE *pCEC
);

Parameters

pCEC
[out, retval] Pointer to CALL_STATE_EVENT_CAUSE indicator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCEC parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallStateEvent, Call Object, CALL_STATE_EVENT_CAUSE


ITCallStateEvent::get_State

The get_State method gets information on the new call state.

HRESULT get_State(
  CALL_STATE *pCallState
);

Parameters

pCallState
[out, retval] Pointer to CALL_STATE constant.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCallState parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCallStateEvent, Call Object, CALL_STATE


ITCollection

The ITCollection interface allows Automation client applications, such as those written in Visual Basic, to retrieve collection information. C or C++ programs use enumerator interfaces to retrieve the same information. Collection methods return a VARIANT which contains a pointer to an ITCollection interface.

The ITCollection2 interface is an extension of the ITCollection interface. ITCollection2 exposes additional methods for modifying the collection.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCollection methods | Description
get_Count | Gets the number of items in the collection.
get_Item | Given an index, returns an item in the collection.
get__NewEnum | Gets an enumerator for the collection.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCollection2


ITCollection::get__NewEnum

The get__NewEnum method gets an enumerator for the collection.

HRESULT get__NewEnum(
  IUnknown **ppNewEnum
);

Parameters

ppNewEnum
[out, retval] Pointer to an IUnknown interface on an enumerator object for the collection.

Call the QueryInterface method on the returned IUnknown interface to obtain a pointer to an IEnumVARIANT enumeration interface on the collection. IEnumVARIANT provides a number of methods that you can use to iterate through the collection.

For more information, see the following Remarks section.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

Each TAPI 3.0 interface that includes a method that returns a collection also includes a method that returns a pointer to a TAPI 3.0 enumerator interface. If you are programming in C/C++, it can be easier to call a collection's enumerator method directly to obtain an enumerator object, instead of calling the ITCollection::get__NewEnum method. For example, the ITTAPI::EnumerateAddresses method returns a pointer to an IEnumAddress interface. IEnumAddress provides enumeration methods for the Address object.

If you are programming in Visual Basic, you do not need to call this method to enumerate a collection. This is because you can invoke the method's functionality implicitly using the For...Each...in...Next... construct.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCollection


ITCollection::get_Count

The get_Count method gets the number of items in the collection.

HRESULT get_Count(
  long *lCount
);

Parameters

lCount
[out, retval] Number of items.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCollection


ITCollection::get_Item

The get_Item method, given an index, returns an item in the collection.

HRESULT get_Item(
  long Index,
  VARIANT *pVariant
);

Parameters

Index
[in] Index of item to be retrieved.
pVariant
[out, retval] Pointer to item returned.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITCollection


ITCollection2

[This is preliminary documentation and subject to change.]

The ITCollection2 interface is an extension of the ITCollection interface. ITCollection2 exposes additional methods for modifying the collection.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCollection2 methods | Description
Add | Adds an item to the collection at the specified index.
Remove | Removes an item from the collection at the specified index.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCollection


ITCollection2::Add

[This is preliminary documentation and subject to change.]

The Add method inserts a new item into the collection at the specified index.

HRESULT Add(
  long Index,
  VARIANT * pVariant
);

Parameters

Index
[in] Specifies the location in the collection where the item should be added.
pVariant
[in] Pointer to a VARIANT containing the item to add.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_INVALIDARG | The Index parameter does not specify a valid index.
E_OUTOFMEMORY | There is not enough memory to reallocate the collection.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCollection2, Remove


ITCollection2::Remove

[This is preliminary documentation and subject to change.]

The Remove method deletes an item from the collection at the specified index.

HRESULT Remove(
  long Index
);

Parameters

Index
[in] Specifies the location in the collection of the item to remove.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Index parameter does not specify a valid index.
E_OUTOFMEMORY | There is not enough memory to reallocate the collection.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCollection2, Add


ITCustomTone

[This is preliminary documentation and subject to change.]

The ITCustomTone interface exposes methods that allow detailed control over the custom tones that are available with some phone sets.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITCustomTone methods | Description
get_Frequency | Gets the frequency, in hertz, of the tone component.
put_Frequency | Sets the frequency, in hertz, of the tone component.
get_CadenceOn | Gets the "on" duration, in milliseconds, of the cadence of the custom tone to generate.
put_CadenceOn | Sets the "on" duration, in milliseconds, of the cadence of the custom tone to generate.
get_CadenceOff | Gets the "off" duration, in milliseconds, of the cadence of the custom tone to generate.
put_CadenceOff | Sets the "off" duration, in milliseconds, of the cadence of the custom tone to generate.
get_Volume | Gets the volume level at which to generate the tone.
put_Volume | Sets the volume level at which to generate the tone.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.


ITCustomTone::get_CadenceOff

[This is preliminary documentation and subject to change.]

The get_CadenceOff method retrieves the "off" duration of the cadence of the custom tone to generate.

HRESULT get_CadenceOff(
  long * plCadenceOff
);

Parameters

plCadenceOff
[out,retval] Pointer to a value to receive the "off" duration, in milliseconds, of the cadence of the custom tone. Zero means no off time, that is, a constant tone.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCadenceOff parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, put_CadenceOff


ITCustomTone::get_CadenceOn

[This is preliminary documentation and subject to change.]

The get_CadenceOn method retrieves the "on" duration of the cadence of the custom tone to generate.

HRESULT get_CadenceOn(
  long * plCadenceOn
);

Parameters

plCadenceOn
[out,retval] Pointer to a value to receive the "on" duration, in milliseconds, of the cadence of the custom tone. Zero means no tone is generated.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCadenceOn parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, put_CadenceOn


ITCustomTone::get_Frequency

[This is preliminary documentation and subject to change.]

The get_Frequency method retrieves the frequency of the tone component to generate.

HRESULT get_Frequency(
  long * plFrequency
);

Parameters

plFrequency
[out,retval] Pointer to a value to receive the frequency, in hertz, of the tone component.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plFrequency parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, put_Frequency


ITCustomTone::get_Volume

[This is preliminary documentation and subject to change.]

The get_Volume method retrieves the volume level at which to generate the tone.

HRESULT get_Volume(
  long * plVolume
);

Parameters

plVolume
[out,retval] Pointer to a value to receive the volume level. A value of 0x0000FFFF represents full volume; a value of 0x00000000 represents silence.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plVolume parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, put_Volume


ITCustomTone::put_CadenceOff

[This is preliminary documentation and subject to change.]

The put_CadenceOff method sets the "off" duration of the cadence of the custom tone to generate.

HRESULT put_CadenceOff(
  long lCadenceOff
);

Parameters

lCadenceOff
[in] Specifies the "off" duration, in milliseconds, of the cadence of the custom tone to generate. Zero means no off time, that is, a constant tone.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, get_CadenceOff


ITCustomTone::put_CadenceOn

[This is preliminary documentation and subject to change.]

The put_CadenceOn method sets the "on" duration of the cadence of the custom tone to generate.

HRESULT put_CadenceOn(
  long CadenceOn
);

Parameters

CadenceOn
[in] Specifies the "on" duration, in milliseconds, of the cadence of the custom tone to generate. Zero means no tone is generated.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, get_CadenceOn


ITCustomTone::put_Frequency

[This is preliminary documentation and subject to change.]

The put_Frequency method sets the frequency of the tone component to generate.

HRESULT put_Frequency(
  long lFrequency
);

Parameters

lFrequency
[in] Specifies the frequency, in hertz, of the tone component.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, get_Frequency


ITCustomTone::put_Volume

[This is preliminary documentation and subject to change.]

The put_Volume method sets the volume level at which to generate the tone.

HRESULT put_Volume(
  long lVolume
);

Parameters

lVolume
[in] Specifies the volume level for the tone. A value of 0x0000FFFF represents full volume; a value of 0x00000000 represents silence.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITCustomTone, get_Volume


ITDetectTone

[This is preliminary documentation and subject to change.]

The ITDetectTone interface exposes methods that allow an application to specify the tones and tone characteristics that should cause the TAPI Server to generate a tone event.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDetectTone methods | Description
get_AppSpecific | Gets the application-defined tag that identifies the tone to detect.
put_AppSpecific | Sets the application-defined tag that identifies the tone to detect.
get_Duration | Gets the length of time during which a tone should be present before the TAPI Server generates a tone event.
put_Duration | Sets the length of time during which a tone should be present before the TAPI Server generates a tone event.
get_Frequency | Gets the frequency of the tone for which the TAPI Server generates a tone event.
put_Frequency | Sets the frequency of the tone for which the TAPI Server generates a tone event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.


ITDetectTone::get_AppSpecific

[This is preliminary documentation and subject to change.]

The get_AppSpecific method retrieves the application-defined tag that identifies the tone to detect.

HRESULT get_AppSpecific(
  long * plAppSpecific
);

Parameters

plAppSpecific
[out,retval] Pointer to a value to receive the application-specific identifier for the tone. When the TAPI Server detects the tone, the value of this parameter is passed back to the application in the TE_TONEEVENT event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plAppSpecific parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDetectTone, put_AppSpecific


ITDetectTone::get_Duration

[This is preliminary documentation and subject to change.]

The get_Duration method retrieves the length of time during which a tone should be present before the TAPI Server generates a tone event.

HRESULT get_Duration(
  long * plDuration
);

Parameters

plDuration
[out,retval] Pointer to a value that receives the tone duration, in milliseconds, during which the specified tone should be present.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plDuration parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDetectTone, put_Duration


ITDetectTone::get_Frequency

[This is preliminary documentation and subject to change.]

The get_Frequency method retrieves the frequency of the tone for which the TAPI Server generates a tone event.

HRESULT get_Frequency(
  long Index,
  long * plFrequency
);

Parameters

Index
[in] Specifies the index of the tone.
plFrequency
[out,retval] Pointer to a value to receive the frequency, in hertz, of the tone. For more information, see the following Remarks section.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plFrequency parameter is not a valid pointer.

Remarks

You can set up to three frequencies that make up the components of a tone. If fewer than three frequencies are required, specify a value of zero for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be used for silence detection.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDetectTone, put_Frequency


ITDetectTone::put_AppSpecific

[This is preliminary documentation and subject to change.]

The put_AppSpecific method sets the application-defined tag that identifies the tone to detect.

HRESULT put_AppSpecific(
  long lAppSpecific
);

Parameters

lAppSpecific
[in] Specifies an application-specific tag that identifies the tone to detect. When the TAPI Server detects the tone, the value of this parameter is passed back to the application in the TE_TONEEVENT event.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDetectTone, get_AppSpecific


ITDetectTone::put_Duration

[This is preliminary documentation and subject to change.]

The put_Duration method sets the length of time during which a tone should be present before the TAPI Server generates a tone event.

HRESULT put_Duration(
  long lDuration
);

Parameters

lDuration
[in] Specifies the tone duration, in milliseconds, during which the specified tone should be present.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDetectTone, get_Duration


ITDetectTone::put_Frequency

[This is preliminary documentation and subject to change.]

The put_Frequency method sets the frequency of the tone for which the TAPI Server should generate a tone event.

HRESULT put_Frequency(
  long Index,
  long lFrequency
);

Parameters

Index
[in] Specifies the index of the tone to set.
lFrequency
[in] Specifies the frequency, in hertz, of the tone. For more information, see the following Remarks section.

Return Values

Value | Meaning
S_OK | Method succeeded.

Remarks

You can set up to three frequencies that make up the components of a tone. If fewer than three frequencies are required, specify a value of zero for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be used for silence detection.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDetectTone, get_Frequency


ITDigitDetectionEvent

The ITDigitDetectionEvent interface contains methods that retrieve the description of DTMF digit events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_DIGITEVENT, the method's pEvent parameter is an IDispatch pointer for the ITDigitDetectionEvent interface. The methods of this interface can be used to detect DTMF digits during a call. This interface is implemented by the application and called by the TAPI 3.0 DLL.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_DIGITEVENT event to enable reception of DTMF digit events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDigitDetectionEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface.
get_Digit | Gets a digit.
get_DigitMode | Gets the descriptor of the line digit mode.
get_TickCount | Gets the "tick count" (number of milliseconds since Windows started) at which the digit-gathering completed.
get_CallbackInstance | Gets the callback instance associated with the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Events, ITTAPIEventNotification, ITTAPI::RegisterCallNotifications, Register Events code snippet


ITDigitDetectionEvent::get_Call

The get_Call method gets a pointer to the ITCallInfo interface for the call on which the event occurred.

HRESULT get_Call(
  ITCallInfo **ppCallInfo
);

Parameters

ppCallInfo
[out, retval] Pointer to ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCallInfo parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitDetectionEvent


ITDigitDetectionEvent::get_CallbackInstance

The get_CallbackInstance method gets a pointer to the callback instance associated with the event.

HRESULT get_CallbackInstance(
  long *plCallbackInstance
);

Parameters

plCallbackInstance
[out, retval] Pointer to the callback instance returned by ITTAPI::RegisterCallNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCallbackInstance parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitDetectionEvent, ITTAPI::RegisterCallNotifications, Call Object


ITDigitDetectionEvent::get_Digit

The get_Digit method retrieves an unsigned char pointer to the digit that was detected.

HRESULT get_Digit(
  unsigned char *pucDigit
);

Parameters

pucDigit
[out, retval] Pointer to the digit.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pucDigit parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitDetectionEvent


ITDigitDetectionEvent::get_DigitMode

The get_DigitMode method gets the indicator of the line digit mode, such as LINEDIGITMODE_DTMF.

HRESULT get_DigitMode(
  TAPI_DIGITMODE *pDigitMode
);

Parameters

pDigitMode
[out, retval] Pointer to indicator of digit mode.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pDigitMode parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitDetectionEvent


ITDigitDetectionEvent::get_TickCount

The get_TickCount method gets the "tick count" (number of milliseconds since Windows started) at which the digit gathering completed.

HRESULT get_TickCount(
  long *plTickCount
);

Parameters

plTickCount
[out, retval] Pointer to tick count.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plTickCount parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitDetectionEvent


ITDigitGenerationEvent

The ITDigitGenerationEvent interface contains methods that describe digit generation events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_GENERATEEVENT, the method's pEvent parameter is an IDispatch pointer for the ITDigitGenerationEvent interface. The methods of this interface can be used to report on calls that require the generation of DTMF digits. This interface is implemented by the application and called by the TAPI 3.0 DLL.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_GENERATEEVENT event to enable reception of digit generation events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDigitGenerationEvent methods | Description
get_Call | Gets an ITCallInfo interface pointer.
get_GenerationTermination | Gets the digit or digits that indicate the end of the generated digit series.
get_TickCount | Gets the "tick count" (number of milliseconds since Windows started) at which the digit-gathering completed.
get_CallbackInstance | Gets the callback instance associated with the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Events, ITTAPIEventNotification, ITTAPI::RegisterCallNotifications, Register Events code snippet


ITDigitGenerationEvent::get_Call

The get_Call method returns an ITCallInfo interface pointer for the call on which the event is required.

HRESULT get_Call(
  ITCallInfo **ppCallInfo
);

Parameters

ppCallInfo
[out] Pointer to ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppCallInfo parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitGenerationEvent


ITDigitGenerationEvent::get_CallbackInstance

The get_CallbackInstance method gets a pointer to the callback instance associated with the event.

HRESULT get_CallbackInstance(
  long *plCallbackInstance
);

Parameters

plCallbackInstance
[out, retval] Pointer to the callback instance returned by ITTAPI::RegisterCallNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCallbackInstance parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitGenerationEvent, ITTAPI::RegisterCallNotifications, Call Object


ITDigitGenerationEvent::get_GenerationTermination

The get_GenerationTermination method gets the digit or digits that indicate the end of the generated digit series.

HRESULT get_GenerationTermination(
  long *plGenerationTermination
);

Parameters

plGenerationTermination
[out, retval] Pointer to digit or digits that indicate the end of the generated digit series.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plGenerationTermination parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitGenerationEvent


ITDigitGenerationEvent::get_TickCount

The get_TickCount method gets the "tick count" (number of milliseconds since Windows started) at which the digit generation completed.

HRESULT get_TickCount(
  long *plTickCount
);

Parameters

plTickCount
[out, retval] Pointer to tick count.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plTickCount parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDigitGenerationEvent


ITDigitsGatheredEvent

[This is preliminary documentation and subject to change.]

The ITDigitsGatheredEvent interface exposes methods that allow an application to retrieve data when the TAPI Server sends an event indicating that the Server has gathered digits required by the application.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDigitsGatheredEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface for the call on which the event occurred.
get_Digits | Gets the gathered digits for the call.
get_GatherTermination | Gets the reason why digit-gathering was terminated.
get_TickCount | Gets the "tick count" (number of milliseconds since Windows started) at which digit-gathering completed.
get_CallbackInstance | Gets a pointer to the application's callback function that will process the event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.


ITDigitsGatheredEvent::get_Call

[This is preliminary documentation and subject to change.]

The get_Call method gets a pointer to the call information interface for the call object on which the event occurred.

HRESULT get_Call(
  ITCallInfo ** ppCallInfo
);

Parameters

ppCallInfo
[out,retval] Pointer to the ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCallInfo parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDigitsGatheredEvent


ITDigitsGatheredEvent::get_CallbackInstance

[This is preliminary documentation and subject to change.]

The get_CallbackInstance method gets a pointer to the application's callback function that will process the event.

HRESULT get_CallbackInstance(
  long * plCallbackInstance
);

Parameters

plCallbackInstance
[out,retval] Pointer to the callback instance returned by ITTAPI::RegisterCallNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCallbackInstance parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDigitsGatheredEvent


ITDigitsGatheredEvent::get_Digits

[This is preliminary documentation and subject to change.]

The get_Digits method gets the gathered digits for the call.

HRESULT get_Digits(
  BSTR * ppDigits
);

Parameters

ppDigits
[out,retval] Pointer to a BSTR where the gathered digits are stored.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppDigits parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDigitsGatheredEvent


ITDigitsGatheredEvent::get_GatherTermination

[This is preliminary documentation and subject to change.]

The get_GatherTermination method gets the reason why the TAPI Server terminated the gathering of digits on the call.

HRESULT get_GatherTermination(
  TAPI_GATHERTERM * pGatherTermination
);

Parameters

pGatherTermination
[out,retval] Pointer to a value from the TAPI_GATHERTERM enumeration.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pGatherTermination parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDigitsGatheredEvent


ITDigitsGatheredEvent::get_TickCount

[This is preliminary documentation and subject to change.]

The get_TickCount method gets the "tick count" (the number of milliseconds since Windows started) at which digit-gathering completed.

HRESULT get_TickCount(
  long * plTickCount
);

Parameters

plTickCount
[out,retval] Pointer to a value to receive the tick count.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plTickCount parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITDigitsGatheredEvent


ITDispatchMapper

The ITDispatchMapper interface allows an application to retrieve the dispatch pointer of another interface on an object, given the dispatch pointer of one interface and the GUID of another. This interface is provided to assist programmers using scripting applications which do not automatically support tracking of multiple interfaces on an object.

The Dispatch Mapper will use the object's IObjectSafety interface to make sure the object is safe for scripting on the requested interface. If the object does not implement IObjectSafety, or if the object is not safe on this particular interface, the call will fail.

The Dispatch Mapper object must be created using COM CoCreateInstance.

Methods in Vtable Order

IDispatch Methods

ITDispatchMapper methods | Description
QueryDispatchInterface | Returns a dispatch pointer to a different interface on an object given its GUID and the dispatch pointer of another interface on the object.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Dispatch Mapper


ITDispatchMapper::QueryDispatchInterface

The QueryDispatchInterface method returns a dispatch pointer to a different interface on an object given its GUID and the dispatch pointer of another interface on the object.

HRESULT QueryDispatchInterface(
  BSTR pIID,
  IDispatch *pInterfaceToMap,
  IDispatch **ppReturnedInterface
);

Parameters

pIID
[in] Pointer to BSTR representation of GUID for needed interface.
pInterfaceToMap
[in] IDispatch pointer of starting interface.
ppReturnedInterface
[out, retval] IDispatch pointer of interface corresponding the GUID contained in pIID.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_INVALIDARG | The pIID parameter either is not a valid BSTR or does not translate into a valid GUID.
E_NOINTERFACE | The interface requested is not exposed or the object does not implement the IObjectSafety interface.

Remarks

The application must use SysAllocString to allocate memory for the pIID parameter and use SysFreeString to free the memory when the variable is no longer needed.

The Dispatch Mapper will use the object's IObjectSafety interface to make sure the object is safe for scripting on the requested interface. If the object does not implement IObjectSafety, or if the object is not safe on this particular interface, the call will fail.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITDispatchMapper


ITFileTerminalEvent

[This is preliminary documentation and subject to change.]

The ITFileTerminalEvent interface contains methods that retrieve the description of file terminal events that have occurred. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_FILETERMINAL, the method's pEvent parameter is an IDispatch pointer for the ITFileTerminalEvent interface.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes TE_FILETERMINAL to enable reception of file terminal events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITFileTerminalEvent methods | Description
get_Terminal | Gets the file terminal that generated this event.
get_Track | Gets the track terminal that generated this event.
get_Call | Gets a pointer to the call information interface for the call on which the event has occurred.
get_State | Gets the new file terminal state.
get_Cause | Gets the cause associated with this event.
get_Error | Gets the error code for the event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITFileTerminalEvent::get_Call

[This is preliminary documentation and subject to change.]

The get_Call method gets a pointer to the call information interface for the call on which the event has occurred.

HRESULT get_Call(
  ITCallInfo ** ppCall
);

Parameters

ppCall
[out,retval] Pointer to the ITCallInfo interface.

Remarks

When a terminal must generate an event, it requires a selected track in order to pass the event to an MSP which will then pass it to the application through TAPI. The first track that accepts the task of sending the event will be used. If the terminal has more than one track and the tracks are selected onto streams that belong to different calls, the call object pointer eventually returned could be for any of those calls.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTerminalEvent, ITCallInfo


ITFileTerminalEvent::get_Cause

[This is preliminary documentation and subject to change.]

The get_Cause method gets the cause associated with this event.

HRESULT get_Cause(
  FT_STATE_EVENT_CAUSE * pCause
);

Parameters

pCause
[out,retval] FT_STATE_EVENT_CAUSE descriptor of the cause of this event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTerminalEvent


ITFileTerminalEvent::get_Error

[This is preliminary documentation and subject to change.]

The get_Error method gets the error code for the event.

HRESULT get_Error(
  HRESULT * phrErrorCode
);

Parameters

phrErrorCode
[out,retval] HRESULT cast of error code associated with this event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTerminalEvent


ITFileTerminalEvent::get_State

[This is preliminary documentation and subject to change.]

The get_State method gets information on the new file terminal state.

HRESULT get_State(
  TERMINAL_MEDIA_STATE * pState
);

Parameters

pState
[out,retval] TERMINAL_MEDIA_STATE descriptor of the new terminal state.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTerminalEvent


ITFileTerminalEvent::get_Terminal

[This is preliminary documentation and subject to change.]

The get_Terminal method returns the file terminal that generated this event.

HRESULT get_Terminal(
  ITTerminal ** ppTerminal
);

Parameters

ppTerminal
[out,retval] Pointer to the ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTerminalEvent, ITTerminal


ITFileTerminalEvent::get_Track

[This is preliminary documentation and subject to change.]

The get_Track method returns the track terminal that generated this event.

HRESULT get_Track(
  ITFileTrack ** ppTrackTerminal
);

Parameters

ppTrackTerminal
[out,retval] Pointer to ITFileTrack interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTerminalEvent


ITFileTrack

[This is preliminary documentation and subject to change.]

The ITFileTrack interface exposes methods that allow an application to get and set information concerning file terminal tracks.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITFileTrack methods | Description
get_Format | Gets the file terminal's format.
put_Format | Sets the file terminal's format.
get_ControllingTerminal | Gets the multitrack terminal that controls the current track.
get_AudioFormatForScripting | Gets the audio scripting format.
put_AudioFormatForScripting | Sets the audio scripting format.
get_EmptyAudioFormatForScripting | Gets an empty audio scripting format.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITFileTrack::get_AudioFormatForScripting

[This is preliminary documentation and subject to change.]

The get_AudioFormatForScripting method gets the video scripting format.

HRESULT get_AudioFormatForScripting(
  ITScriptableAudioFormat ** ppAudioFormat
);

Parameters

ppAudioFormat
[out,retval] Pointer to the ITScriptableAudioFormat interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTrack


ITFileTrack::get_ControllingTerminal

[This is preliminary documentation and subject to change.]

The get_ControllingTerminal method returns the multitrack terminal that controls the current track.

HRESULT get_ControllingTerminal(
  ITTerminal ** ppControllingTerminal
);

Parameters

ppControllingTerminal
[out,retval] Pointer to the ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTrack, ITTerminal


ITFileTrack::get_EmptyAudioFormatForScripting

[This is preliminary documentation and subject to change.]

The get_EmptyAudioFormatForScripting method is used to get an ITScriptableAudioFormat interface with all fields set to 0.

HRESULT get_EmptyAudioFormatForScripting(
  ITScriptableAudioFormat ** ppAudioFormat
);

Parameters

ppAudioFormat
[out,retval] Pointer to ITScriptableAudioFormat interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTrack


ITFileTrack::get_Format

[This is preliminary documentation and subject to change.]

The get_Format method gets the file terminal's format.

HRESULT get_Format(
  AM_MEDIA_TYPE ** ppmt
);

Parameters

ppmt
[out,retval] Pointer to an AM_MEDIA_TYPE descriptor of the terminal format.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTrack


ITFileTrack::put_AudioFormatForScripting

[This is preliminary documentation and subject to change.]

The put_AudioFormatForScripting method sets the audio scripting format.

HRESULT put_AudioFormatForScripting(
  ITScriptableAudioFormat * pAudioFormat
);

Parameters

pAudioFormat
[in] Pointer to the ITScriptableAudioFormat interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTrack


ITFileTrack::put_Format

[This is preliminary documentation and subject to change.]

The put_Format method sets the format type of the track.

HRESULT put_Format(
  const AM_MEDIA_TYPE * pmt
);

Parameters

pmt
[in] AM_MEDIA_TYPE descriptor of the file track's format.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITFileTrack


ITForwardInformation

The ITForwardInformation interface provides methods for setup and implementation of call forwarding. The forward information object is created by ITAddress::CreateForwardInfoObject. A pointer to an existing forward information object can be retrieved using ITAddress::get_CurrentForwardInfo.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITForwardInformation methods | Description
put_NumRingsNoAnswer | Sets the number of rings after which a no answer condition is assumed.
get_NumRingsNoAnswer | Retrieves the number of rings after which a no answer condition is assumed.
SetForwardType | Sets the forwarding mode.
get_ForwardTypeDestination | Gets the destination for a forwarding mode.
get_ForwardTypeCaller | Gets the type of caller for a forwarding mode.
GetForwardType | Gets the forwarding mode.
Clear | Clears all forwarding information in this object.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, Terminal Object


ITForwardInformation::Clear

The Clear method clears all forwarding information in this object.

HRESULT Clear();

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

This method does not clear forwarding information in the service provider.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, Terminal Object


ITForwardInformation::GetForwardType

The GetForwardType method gets the forwarding mode.

HRESULT GetForwardType(
  long ForwardType,
  BSTR *ppDestinationAddress,
  BSTR *ppCallerAddress
);

Parameters

ForwardType
[in] Line forward mode.
ppDestinationAddress
[out] Pointer to BSTR representation of destination address.
ppCallerAddress
[out, retval] Pointer to BSTR representation of the call originator's address.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppDestAddress or ppCallerAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppDestinationAddress and ppCallerAddress parameters.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, Terminal Object


ITForwardInformation::SetForwardType

The SetForwardType method sets the forwarding mode and destination by caller address.

HRESULT SetForwardType(
  long ForwardType,
  BSTR pDestAddress,
  BSTR pCallerAddress
);

Parameters

ForwardType
[in] Line forward mode.
pDestAddress
[in] Pointer to BSTR representation of destination address for fowarding.
pCallerAddress
[in] Pointer to BSTR representation of caller address.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDestAddress or pCallerAddress parameter is not a valid pointer.
E_INVALIDARG | The ForwardType parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysAllocString to allocate memory for the pDestAddress and pCallerAddress parameters. The application must use SysFreeString to free the memory when the variables are no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, Terminal Object


ITForwardInformation::get_ForwardTypeCaller

The get_ForwardTypeCaller method gets the type of caller for a given forwarding mode.

HRESULT get_ForwardTypeCaller(
  long Forwardtype,
  BSTR *ppCallerAddress
);

Parameters

Forwardtype
[in] Line forward mode.
ppCallerAddress
[out, retval] Pointer to BSTR representation of caller address.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCallerAddress parameter is not a valid pointer.
E_INVALIDARG | The Forwardtype parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCallerAddress parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, Terminal Object


ITForwardInformation::get_ForwardTypeDestination

The get_ForwardTypeDestination method gets the destination for a forwarding mode.

HRESULT get_ForwardTypeDestination(
  long ForwardType,
  BSTR *ppDestAddress
);

Parameters

ForwardType
[in] Line forward mode.
ppDestAddress
[out, retval] Pointer to BSTR representation of destination address.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppDestAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppDestAddress parameter is not a valid pointer.

Remarks

The application must use SysFreeString to free the memory allocated for the ppDestAddress parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, Terminal Object


ITForwardInformation::get_NumRingsNoAnswer

The get_NumRingsNoAnswer method retrieves the number of rings after which a no answer condition is assumed.

HRESULT get_NumRingsNoAnswer(
  long *plNumRings
);

Parameters

plNumRings
[out, retval] Pointer to number of rings.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plNumRings parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, put_NumRingsNoAnswer, Terminal Object


ITForwardInformation::put_NumRingsNoAnswer

The put_NumRingsNoAnswer method sets the number of rings after which a no answer condition is assumed.

HRESULT put_NumRingsNoAnswer(
  long lNumRings
);

Parameters

lNumRings
[in] Number of rings.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITForwardInformation, ITAddress::CreateForwardInfoObject, ITAddress::Forward, ITAddress::get_CurrentForwardInfo, get_NumRingsNoAnswer, Terminal Object


ITLegacyAddressMediaControl

The ITLegacyAddressMediaControl interface is provided to support legacy applications that require direct access to a device and its configuration. It is exposed by the Address Object.

The ITLegacyAddressMediaControl2 interface derives from the ITLegacyAddressMediaControl interface. ITLegacyAddressMediaControl2 provides additional methods that allow the configuration of parameters related to line devices.

Methods in Vtable Order

IUnknown Methods

ITLegacyAddressMediaControl methods | Description
GetID | Gets device identifier.
GetDevConfig | Gets pointer to device-specific array of configuration information.
SetDevConfig | Sets device-specific array of configuration information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyAddressMediaControl2


ITLegacyAddressMediaControl::GetDevConfig

The GetDevConfig method returns an opaque data structure. The exact contents are specific to the service provider and device class. The data structure specifies the configuration of a device associated with a particular line device. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a datamodem device associated with the line.

HRESULT GetDevConfig(
  BSTR pDeviceClass,
  DWORD *pdwSize,
  BYTE **ppDeviceConfig
);

Parameters

pDeviceClass
[in] Pointer to BSTR containing TAPI device class for which configuration information is needed.
pdwSize
[out] Pointer to size of configuration array.
ppDeviceConfig
[out, size_is(,*pdwSize)] Pointer to array of bytes containing device configuration information.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDeviceClass, pdwSize, or ppDeviceConfig parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

This method is a COM wrapper for the LineGetDevConfig TAPI 2.1 function.

The GetID must be performed prior to calling this method.

The application must use SysAllocString to allocate memory for the pDeviceClass parameter and use SysFreeString to free the memory when the variable is no longer needed.

The application must call the CoTaskMemFree function to free the memory allocated for the ppDeviceConfig parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyAddressMediaControl, SetDevConfig, ITLegacyCallMediaControl

TAPI 2.1 Cross-reference: LineGetDevConfig, LineSetDevConfig


ITLegacyAddressMediaControl::GetID

The GetID method returns a device identifier for the specified device class associated with the current address.

HRESULT GetID(
  BSTR pDeviceClass,
  DWORD *pdwSize,
  BYTE **ppDeviceID
);

Parameters

pDeviceClass
[in] Pointer to BSTR containing TAPI device class for which configuration information is needed.
pdwSize
[out] Length of device identifier returned.
ppDeviceID
[out, size_is(,*pdwSize)] Device identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Method failed. This may mean there is no device of a specified class associated with the current address.
E_POINTER | The pdwSize or ppDeviceID parameter is not a valid pointer.

Remarks

The application must use SysAllocString to allocate memory for the pDeviceClass parameter and use SysFreeString to free the memory when the variable is no longer needed.

The application must call the CoTaskMemFree function to free the memory allocated for the ppDeviceID parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyAddressMediaControl, GetDevConfig, SetDevConfig, ITLegacyCallMediaControl

TAPI 2.1 Cross-reference: LineGetDevConfig, LineSetDevConfig, lineGetID


ITLegacyAddressMediaControl::SetDevConfig

The SetDevConfig function allows the application to restore the configuration of a media stream device on a line device to a setup previously obtained using GetDevConfig.

HRESULT SetDevConfig(
  BSTR pDeviceClass,
  DWORD dwSize,
  BYTE *pDeviceConfig
);

Parameters

pDeviceClass
[in] Pointer to BSTR containing TAPI device class for which configuration information is needed.
dwSize
[in] Size of configuration array.
pDeviceConfig
[in, size_is(dwSize)] Pointer to the array of bytes containing device configuration information obtained by a call to GetDevConfig.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDeviceClass, pdwSize, or ppDeviceConfig parameter is not a valid pointer.
E_INVALIDARG | The pdwSize parameter is zero.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

This method is a COM wrapper for the LineSetDevConfig TAPI 2.1 function.

The GetID must be performed prior to calling this method.

The application must use SysAllocString to allocate memory for the pDeviceClass parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyAddressMediaControl, GetDevConfig, ITLegacyCallMediaControl

TAPI 2.1 Cross-reference: LineGetDevConfig, LineSetDevConfig


ITLegacyAddressMediaControl2

[This is preliminary documentation and subject to change.]

The ITLegacyAddressMediaControl2 interface derives from the ITLegacyAddressMediaControl interface. ITLegacyAddressMediaControl2 provides additional methods that allow the configuration of parameters related to line devices.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITLegacyAddressMediaControl2 methods | Description
ConfigDialog | Displays a dialog box to allow the user to configure parameters related to the specified line device. The parameters that can be edited are those currently in use on the device.
ConfigDialogEdit | Displays a dialog box to allow the user to configure parameters related to the specified line device. The parameters to edit are passed in from the application, and the results are returned to the application.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyAddressMediaControl


ITLegacyAddressMediaControl2::ConfigDialog

[This is preliminary documentation and subject to change.]

The ConfigDialog method causes the provider of the specified line device to display a dialog box to allow the user to configure parameters related to the line device. The parameters that can be edited are those currently in use on the device.

HRESULT ConfigDialog(
  HWND hwndOwner,
  BSTR pDeviceClass
);

Parameters

hwndOwner
[in] A handle to a window to which the dialog box is to be attached. This parameter can be NULL to indicate that a window created by the method should have no owner window.
pDeviceClass
[in] Pointer to a BSTR that specifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level configuration is selected.

Remarks

This method translates to a TAPI 2.x lineConfigDialog function call. The ITLegacyAddressMediaControl2::ConfigDialogEdit method translates to a lineConfigDialogEdit call. These methods differ in their source of parameters to edit and the result of the editing on an active connection. For a discussion about these differences, see lineConfigDialogEdit.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyAddressMediaControl2


ITLegacyAddressMediaControl2::ConfigDialogEdit

[This is preliminary documentation and subject to change.]

The ConfigDialogEdit method causes the provider of the specified line device to display a dialog box to allow the user to configure parameters related to the line device. The configuration data is passed in and out of this method by the application. (The data is the same as that retrieved by the ITLegacyAddressMediaControl::GetDevConfig method and set by the ITLegacyAddressMediaControl::SetDevConfig method.)

HRESULT ConfigDialogEdit(
  HWND hwndOwner,
  BSTR pDeviceClass,
  DWORD dwSizeIn,
  BYTE * pDeviceConfigIn,
  DWORD * pdwSizeOut,
  BYTE ** ppDeviceConfigOut
);

Parameters

hwndOwner
[in] A handle to a window to which the dialog box is to be attached. Can be NULL to indicate that a window created by the method should have no owner window.
pDeviceClass
[in] Pointer to a BSTR that specifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.
dwSizeIn
[in] Pointer to the size of the configuration data pointed to by the pDeviceConfigIn parameter.
pDeviceConfigIn
[in, size_is(dwSizeIn)] Pointer to an array of bytes containing device configuration data to edit.
pdwSizeOut
[out] Pointer to the size of the configuration data pointed to by the ppDeviceConfigOut parameter.
ppDeviceConfigOut
[out, size_is(,*pdwSizeOut)] Pointer to an array of bytes containing edited device configuration data.

Remarks

This method translates to a TAPI 2.x lineConfigDialogEdit call. The ITLegacyAddressMediaControl2::ConfigDialog method translates to a lineConfigDialog call. These methods differ in their source of parameters to edit and the result of the editing on an active connection. For a discussion about these differences, see lineConfigDialogEdit.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyAddressMediaControl2, ITLegacyAddressMediaControl2::ConfigDialog


ITLegacyCallMediaControl

The ITLegacyCallMediaControl interface supports legacy applications that must communicate directly with a device. This interface is exposed on the Call Object.

The ITLegacyCallMediaControl2 interface is an extension of the ITLegacyCallMediaControl interface. ITLegacyCallMediaControl2 provides additional methods, primarily for tone detection and generation.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITLegacyCallMediaControl methods | Description
DetectDigits | Sets mode for digit detection.
GenerateDigits | Sends digits to call destination.
GetID | Gets identifier for device associated with the current call. This method is intended for Visual Basic and scripting applications.
SetMediaType | Sets media type for call.
MonitorMedia | Sets monitoring for a given media type.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2


ITLegacyCallMediaControl::DetectDigits

The DetectDigits method sets an identifier of the type of digits that will be detected on the current call, such as rotary pulse or DTMF.

HRESULT DetectDigits(
  TAPI_DIGITMODE DigitMode
);

Parameters

DigitMode
[in] Indicates digit mode.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALCALLSTATE | No call currently exists.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl, ITLegacyAddressMediaControl


ITLegacyCallMediaControl::GenerateDigits

The GenerateDigits method causes digits to be output on the current call.

HRESULT GenerateDigits(
  BSTR pDigits,
  TAPI_DIGITMODE DigitMode
);

Parameters

pDigits
[in] Pointer to BSTR representation of digits to be sent.
DigitMode
[in] Indicates digit mode.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALCALLSTATE | No call currently exists.

Remarks

The application must use SysAllocString to allocate memory for the pDigits parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl, ITLegacyAddressMediaControl


ITLegacyCallMediaControl::GetID

The GetID method gets the identifier for the device associated with the current call.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the GetIDAsVariant method instead.

HRESULT GetID(
  BSTR pDeviceClass,
  DWORD *pdwSize,
  BYTE **ppDeviceID
);

Parameters

pDeviceClass
[in] Pointer to BSTR representing the TAPI device class.
pdwSize
[out] Size in bytes of device identifier.
ppDeviceID
[out, size_is(,*pdwSize)] Device identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pdwSize or ppDeviceID parameter is not a valid pointer.

Remarks

The application must use SysAllocString to allocate memory for the pDeviceClass parameter and use SysFreeString to free the memory when the variable is no longer needed.

The application must call the CoTaskMemFree function to free the memory allocated for the ppDeviceID parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl, ITLegacyCallMediaControl2::GetIDAsVariant, ITLegacyAddressMediaControl


ITLegacyCallMediaControl::SetMediaType

The SetMediaType method sets the media type(s) for the current call in its LINECALLINFO structure. For more information, see lineSetMediaMode.

HRESULT SetMediaType(
  long lMediaType
);

Parameters

lMediaType
[in] Indicator of media type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | The associated call object is not valid.
E_INVALIDARG | The lMediaType parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl, ITLegacyAddressMediaControl


ITLegacyCallMediaControl::MonitorMedia

The MonitorMedia method sets monitoring for a given media type on the current call. This method enables and disables the detection of media types (modes) on the specified call. When a media type is detected, a message is sent to the application. For more information, see lineMonitorMedia.

HRESULT MonitorMedia(
  long lMediaType
);

Parameters

lMediaType
[in] Indicator of media type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The lMediaType parameter is not valid.
E_FAIL | The associated call object is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl, ITLegacyAddressMediaControl


ITLegacyCallMediaControl2

[This is preliminary documentation and subject to change.]

The ITLegacyCallMediaControl2 interface is an extension of the ITLegacyCallMediaControl interface. ITLegacyCallMediaControl2 provides additional methods, primarily for tone detection and generation.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITLegacyCallMediaControl2 methods | Description
GenerateDigits2 | Causes digits to be output on the current call.
GatherDigits | Initiates the gathering of digits on the specified call; extends the ITLegacyCallMediaControl::GenerateDigits method by adding a duration parameter.
DetectTones | Enables and disables the detection of inband tones on the call. This method is intended for C/C++ applications.
DetectTonesByCollection | Enables and disables the detection of inband tones on the call. This method is intended for Visual Basic and scripting applications.
GenerateTone | Generates a specified tone.
GenerateCustomTones | Generates a specified custom tone. This method is intended for C/C++ applications.
GenerateCustomTonesByCollection | Generates a specified custom tone. This method is intended for Visual Basic and scripting applications.
GetIDAsVariant | Gets the identifier for the device associated with the current call. (Hidden from scripting languages.)
CreateDetectToneObject | Creates a detect tone object to use with the DetectTonesByCollection method. This method is intended for Visual Basic and scripting applications.
CreateCustomToneObject | Creates a custom tone object to use with the GenerateCustomTonesByCollection method. This method is intended for Visual Basic and scripting applications.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl


ITLegacyCallMediaControl2::CreateCustomToneObject

[This is preliminary documentation and subject to change.]

The CreateCustomToneObject method creates a custom tone object to use with the GenerateCustomTonesByCollection method.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the GenerateCustomTones method instead.

HRESULT CreateCustomToneObject(
  ITCustomTone ** ppCustomTone
);

Parameters

ppCustomTone
[out,retval] Pointer to an ITCustomTone interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCustomTone parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2, ITCustomTone, GenerateCustomTonesByCollection


ITLegacyCallMediaControl2::CreateDetectToneObject

[This is preliminary documentation and subject to change.]

The CreateDetectToneObject method creates a detect tone object to use with the DetectTonesByCollection method.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the DetectTones method instead.

HRESULT CreateDetectToneObject(
  ITDetectTone ** ppDetectTone
);

Parameters

ppDetectTone
[out,retval] Pointer to an ITDetectTone interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppDetectTone parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2, ITDetectTone, DetectTonesByCollection


ITLegacyCallMediaControl2::DetectTones

[This is preliminary documentation and subject to change.]

The DetectTones method enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is sent to the application.

This method is intended for C/C++ applications. Visual Basic and scripting applications should use the DetectTonesByCollection method instead.

HRESULT DetectTones(
  TAPI_DETECTTONE * pToneList,
  long lNumTones
);

Parameters

pToneList
[in] Pointer to a TAPI_DETECTTONE array that specifies the tones to detect. Each tone in the array has an application-defined tag field that is used to identify the individual tones in the list when a tone detection event of type TE_TONEEVENT is reported. For more information, see the following Remarks section.
lNumTones
[in] The number of entries in the array specified by the pToneList parameter. This parameter is ignored if pToneList is NULL.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pToneList parameter is not a valid pointer.
TAPI_E_INVALCALLSTATE | The call must be in the connected state.

Remarks

This method translates to a TAPI 2.x lineMonitorTones call.

To cancel tone monitoring in progress, call the DetectTones method and specify a NULL pToneList parameter. To change the list of tones to monitor, call this method and specify a new tone list.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2


ITLegacyCallMediaControl2::DetectTonesByCollection

[This is preliminary documentation and subject to change.]

The DetectTonesByCollection method enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is sent to the application.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the DetectTones method instead.

HRESULT DetectTonesByCollection(
  ITCollection2 * pDetectToneCollection
);

Parameters

pDetectToneCollection
[in] Pointer to an ITCollection2 interface containing a collection of ITDetectTone interface pointers that represent the tones to monitor. Each tone in the list has an application-defined tag field that is used to identify the individual tones when tone detection is reported by a TE_TONEEVENT event. For more information, see the following Remarks section.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDetectToneCollection parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the tones buffer.
TAPI_E_INVALCALLSTATE | The call must be in the connected state.

Remarks

This method translates to a TAPI 2.x lineMonitorTones call.

To cancel tone monitoring in progress, call the DetectTonesByCollection method and specify an empty collection. To change the list of tones to monitor, call this method and specify a new tone collection.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2, ITCollection2, ITDetectTone


ITLegacyCallMediaControl2::GatherDigits

[This is preliminary documentation and subject to change.]

The GatherDigits method initiates the gathering of digits on the specified call. The application specifies the maximum number of digits to collect.

HRESULT GatherDigits(
  TAPI_DIGITMODE DigitMode,
  long lNumDigits,
  BSTR pTerminationDigits,
  long lFirstDigitTimeout,
  long lInterDigitTimeout
);

Parameters

DigitMode
[in] The digit mode(s) to monitor. This parameter specifies one or more of the LINEDIGITMODE constants.
lNumDigits
[in] The number of digits to collect.

If this parameter is zero, the method cancels any digit-gathering in progress, without starting a new digit-gathering attempt. For more information, see the following Remarks section.

pTerminationDigits
[in] Pointer to a BSTR representation of the termination digits. If one of the termination digits in the string is detected, that digit is appended to the buffer, digit collection is terminated, and the TE_GATHERDIGITS event is sent to the application.
lFirstDigitTimeout
[in] The length of time, in milliseconds, during which the first digit is expected. If the first digit is not received in this timeframe, digit collection is aborted and a TE_GATHERDIGITS event is sent to the application. The buffer contains only the NULL character, indicating that no digits were received and that the first-digit-timeout terminated digit-gathering. The minimum and maximum timeouts you can specify are found in the AC_GATHERDIGITSMINTIMEOUT and AC_GATHERDIGITSMAXTIMEOUT capabilities.
lInterDigitTimeout
[in] The maximum time, in milliseconds, between consecutive digits. If the next digit is not received in this timeframe, digit collection is aborted and a TE_GATHERDIGITS event is sent to the application. The buffer contains only the digits collected up to this point followed by a NULL character, indicating that an interdigit-timeout terminated the digit-gathering. The minimum and maximum timeouts that can be specified are found in the AC_GATHERDIGITSMINTIMEOUT and AC_GATHERDIGITSMAXTIMEOUT capabilities.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminationDigits parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the gather digits buffer.
TAPI_E_INVALCALLSTATE | The call must be in the connected state.

Remarks

The GatherDigits method translates to a call to the TAPI 2.x lineGatherDigits function.

Only one GatherDigits call can be outstanding on a call. If you call GatherDigits again, before the TE_GATHERDIGITS event has occurred, the second call cancels the previous gathering of digits. Cancelled digit-gathering attempts send a TE_GATHERDIGITS event with the digits collected so far.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2


ITLegacyCallMediaControl2::GenerateCustomTones

[This is preliminary documentation and subject to change.]

The GenerateCustomTones method generates the specified custom tone.

This method is intended for C/C++ applications. Visual Basic and scripting applications should use the GenerateCustomTonesByCollection method instead.

HRESULT GenerateCustomTones(
  TAPI_CUSTOMTONE * pToneList,
  long lNumTones,
  long lDuration
);

Parameters

pToneList
[in] Pointer to a TAPI_DETECTTONE array that specifies the tones to generate.
lNumTones
[in] The number of entries in the array specified by the pToneList parameter.
lDuration
[in] The duration, in milliseconds, during which the tone should be sustained.

Remarks

This method translates to a call to the TAPI 2.x lineGenerateTone function.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2


ITLegacyCallMediaControl2::GenerateCustomTonesByCollection

[This is preliminary documentation and subject to change.]

The GenerateCustomTonesByCollection method generates the specified custom tone.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the GenerateCustomTones method instead.

HRESULT GenerateCustomTonesByCollection(
  ITCollection2 * pCustomToneCollection,
  long lDuration
);

Parameters

pCustomToneCollection
[in] Pointer to an ITCollection2 interface containing a collection of ITCustomTone interface pointers representing the tone's components. If the collection is a multifrequency tone, the various tones are played simultaneously.
lDuration
[in] The duration, in milliseconds, during which the tone should be sustained. A value of zero uses a default duration.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pCustomToneCollection parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the tones buffer.
TAPI_E_INVALCALLSTATE | The call must be in the connected state.

Remarks

This method translates to a call to the TAPI 2.x lineGenerateTone function.

When tone generation finishes, an event of type TE_GENERATEEVENT is generated.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2, ITCollection2, ITCustomTone


ITLegacyCallMediaControl2::GenerateDigits2

[This is preliminary documentation and subject to change.]

The GenerateDigits2 method causes digits to be output on the current call. This method extends the ITLegacyCallMediaControl::GenerateDigits method by adding a duration parameter.

HRESULT GenerateDigits2(
  BSTR pDigits,
  TAPI_DIGITMODE DigitMode,
  long lDuration
);

Parameters

pDigits
[in] A pointer to a BSTR representation of the digits to generate.
DigitMode
[in] Indicates the digit mode. Valid values are those from the TAPI 2.x LINEDIGITMODE_constants.
lDuration
[in] Both the duration, in milliseconds, of DTMF digits and pulse, and DTMF interdigit spacing.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDigits parameter is not a valid pointer.
TAPI_E_INVALCALLSTATE | The call must be in the connected state.

Remarks

This method translates to a call to the TAPI 2.x lineGenerateDigits function.

When digit generation finishes, an event of type TE_GENERATEEVENT is generated.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2


ITLegacyCallMediaControl2::GenerateTone

[This is preliminary documentation and subject to change.]

The GenerateTone method generates the specified tone.

To generate custom tones, call the GenerateCustomTones (C/C++) or the GenerateCustomTonesByCollection method (Visual Basic and scripting applications).

HRESULT GenerateTone(
  TAPI_TONEMODE ToneMode,
  long lDuration
);

Parameters

ToneMode
[in] Indicates the tone mode. The values used are those from the TAPI_TONEMODE enumeration.
lDuration
[in] Both the duration, in milliseconds, of DTMF digits and pulse, and DTMF interdigit spacing.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | One of the parameters is invalid.
TAPI_E_INVALCALLSTATE | The call must be in the connected state.

Remarks

This method translates to a call to the TAPI 2.x lineGenerateTone function.

When tone generation finishes, an event of type TE_GENERATEEVENT is generated.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2


ITLegacyCallMediaControl2::GetIDAsVariant

The GetIDAsVariant method gets the identifier for the device associated with the current call.

HRESULT GetIDAsVariant(
  BSTR bstrDeviceClass,
  VARIANT * pVarDeviceID
);

Parameters

bstrDeviceClass
[in] BSTR representing the TAPI device class.
pVarDeviceID
[out retval] Pointer to a variant array of bytes of type VT_ARRAY | VT_UI1 which contains the identifier for the device specified in bstrDeviceClass.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVarDeviceID parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITLegacyCallMediaControl2, ITLegacyAddressMediaControl, ITLegacyCallMediaControl::GetID


ITLegacyWaveSupport

The ITLegacyWaveSupport interface allows an application to discover whether a terminal created by a legacy TSP (pre-TAPI 3) can be controlled using the Win32 Wave API.

Methods in Vtable Order

ITLegacyWaveSupport methods | Description
IsFullDuplex | Gets indicator of whether address supports wave devices.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

FULLDUPLEX_SUPPORT


ITLegacyWaveSupport::IsFullDuplex

The IsFullDuplex method gets an indicator of whether the address supports wave devices.

HRESULT IsFullDuplex(
  FULLDUPLEX_SUPPORT *pSupport
);

Parameters

pSupport
Pointer to FULLDUPLEX_SUPPORT enumerator member, such as FDS_SUPPORTED.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLegacyWaveSupport, FULLDUPLEX_SUPPORT


ITLocalParticipant

The ITLocalParticipant interface is exposed on the stream object when the IPConf MSP supports the call. The MSP implements methods that allow an application to get and set participant information.

Methods in Vtable Order

ITLocalParticipant methods | Description
get_LocalParticipantTypedInfo | Gets participant information, such as e-mail name or geographical location.
put_LocalParticipantTypedInfo | Sets participant information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.


ITLocalParticipant::get_LocalParticipantTypedInfo

The get_LocalParticipantTypedInfo method gets participant information, such as e-mail name or geographical location.

HRESULT get_LocalParticipantTypedInfo(
  PARTICIPANT_TYPED_INFO InfoType,
  BSTR *ppInfo
);

Parameters

InfoType
[in] PARTICIPANT_TYPED_INFO identifier of type of information required.
ppInfo
[out, retval] Pointer to a BSTR that will contain the required information following a successful return of the method.

Remarks

The application must use SysFreeString to free the memory allocated for the ppInfo parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITLocalParticipant, PARTICIPANT_TYPED_INFO


ITLocalParticipant::put_LocalParticipantTypedInfo

The put_LocalParticipantTypedInfo method sets participant information.

HRESULT put_LocalParticipantTypedInfo(
  PARTICIPANT_TYPED_INFO InfoType,
  BSTR ppInfo
);

Parameters

InfoType
[in] PARTICIPANT_TYPED_INFO identifier of the type of information required.
ppInfo
[in] BSTR containing the required new value for the information.

Remarks

The application must use SysAllocString to allocate memory for the ppInfo parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITLocalParticipant, PARTICIPANT_TYPED_INFO


ITLocationInfo

The ITLocationInfo interface is used to get information related to the location of the calling party. This is the location information that is entered by using the Telephony applet under the Control Panel.

An ITLocationInfo interface pointer is obtained by using ITAddressTranslation::EnumerateLocations or ITAddressTranslation::get_Locations. There can be more than one location entries in the Telephony applet. If so, EnumerateLocations and get_Locations will return them all. However, only one of them is the current location, and TAPI uses that one as the address translation context when ITAddressTranslation::TranslateAddress is called.

The ITLocationInfo interface is a COM wrapper for the TAPI 2.x LINELOCATIONENTRY structure.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITLocationInfo methods | Description
get_PermanentLocationID | Gets permanent location identifier.
get_CountryCode | Gets country code.
get_CountryID | Gets identifier for country/region.
get_Options | Gets indicator of whether the current location supports pulse or tone dialing.
get_PreferredCardID | Gets preferred calling card identifier.
get_LocationName | Gets location name.
get_CityCode | Gets code for city or area.
get_LocalAccessCode | Gets local access code.
get_LongDistanceAccessCode | Gets code to access long distance.
get_TollPrefixList | Gets toll prefix list.
get_CancelCallWaitingCode | Gets the dial digits and modifier characters required to cancel call waiting.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddressTranslation::EnumerateLocations, ITAddressTranslation::get_Locations, ITAddressTranslation::TranslateAddress, lineGetTranslateCaps, LINELOCATIONENTRY


ITLocationInfo::get_CancelCallWaitingCode

The get_CancelCallWaitingCode method gets the dial digits and modifier characters that must be prefixed to a dialable string to cancel call waiting.

HRESULT get_CancelCallWaitingCode(
  BSTR *ppCode
);

Parameters

ppCode
[out, retval] Pointer to BSTR representation of dial digits and modifier characters required to cancel call waiting.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCode parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCode parameter.

The value that this method returns corresponds to the dwCancelCallWaitingSize and dwCancelCallWaitingOffset members of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_CityCode

The get_CityCode method gets the code for the city.

HRESULT get_CityCode(
  BSTR *ppCode
);

Parameters

ppCode
[out, retval] Pointer to the BSTR representation of the city code.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCode parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCode parameter.

The value that this method returns corresponds to the dwCityCodeSize and dwCityCodeOffset members of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_CountryCode

The get_CountryCode method gets the country code.

HRESULT get_CountryCode(
  long *plCountryCode
);

Parameters

plCountryCode
[out, retval] Pointer to country code.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCountryCode parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The value that this method returns corresponds to the dwCountryCode member of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_CountryID

The get_CountryID method gets the identifier for the country/region.

HRESULT get_CountryID(
  long *plCountryID
);

Parameters

plCountryID
[out, retval] Country/region ID.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ulCountryID parameter is not valid.
E_POINTER | The ulCountryID parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The value that this method returns corresponds to the dwCountryID member of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_LocalAccessCode

The get_LocalAccessCode method gets the local access code.

HRESULT get_LocalAccessCode(
  BSTR *ppCode
);

Parameters

ppCode
[out, retval] Pointer to BSTR representation of local access code.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppCode parameter is not valid.
E_POINTER | The ppCode parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCode parameter.

The value that this method returns corresponds to the dwLocalAccessCodeSize and dwLocalAccessCodeOffset members of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_LocationName

The get_LocationName method gets the location name.

HRESULT get_LocationName(
  BSTR *ppLocationName
);

Parameters

ppLocationName
[out, retval] Pointer to the BSTR representation of the location name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppLocationName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppLocationName parameter.

The value that this method returns corresponds to the dwLocationNameSize and dwLocationNameOffset members of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_LongDistanceAccessCode

The get_LongDistanceAccessCode method gets the code to access long distance.

HRESULT get_LongDistanceAccessCode(
  BSTR *ppCode
);

Parameters

ppCode
[out, retval] Pointer to BSTR representation of long distance access code.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppCode parameter is not valid.
E_POINTER | The ppCode parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCode parameter.

The value that this method returns corresponds to the dwLongDistanceAccessCodeSize and dwLongDistanceAccessCodeOffset members of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_Options

The get_Options method gets an indicator of whether the current location supports pulse or tone dialing.

HRESULT get_Options(
  long *plOptions
);

Parameters

plOptions
[out, retval] Dialing options, as indicated by values from LINELOCATIONOPTION_ Constants.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plOptions parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The value that this method returns corresponds to the dwOptions member of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, LINELOCATIONENTRY, lineGetTranslateCaps


ITLocationInfo::get_PermanentLocationID

The get_PermanentLocationID method gets the permanent location identifier.

HRESULT get_PermanentLocationID(
  long *plLocationID
);

Parameters

plLocationID
[out, retval] Pointer to the permanent location identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plLocationID parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The value that this method returns corresponds to the dwPermanentLocationID member of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, lineGetTranslateCaps, LINELOCATIONENTRY


ITLocationInfo::get_PreferredCardID

The get_PreferredCardID method gets the preferred calling card identifier for dialing from the current location.

HRESULT get_PreferredCardID(
  long *plCardID
);

Parameters

plCardID
[out, retval] Calling card ID.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCardID parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The value that this method returns corresponds to the dwPreferredCardID member of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, lineGetTranslateCaps, LINELOCATIONENTRY


ITLocationInfo::get_TollPrefixList

The get_TollPrefixList method gets the toll prefix list.

HRESULT get_TollPrefixList(
  BSTR *ppTollList
);

Parameters

ppTollList
[out, retval] Pointer to the BSTR containing a list of toll prefixes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTollList parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppTollList parameter.

The value that this method returns corresponds to the dwTollPrefixListSize and dwTollPrefixListOffset members of TAPI 2's LINELOCATIONENTRY structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITLocationInfo, lineGetTranslateCaps, LINELOCATIONENTRY


ITMediaControl

[This is preliminary documentation and subject to change.]

The ITMediaControl interface is a generic interface for media file terminals. The interface exposes methods that allow the application to start, stop, or pause current actions, such as a playback.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITMediaControl methods | Description
Start | Starts the action at the current file location.
Stop | Stops the current action, and sets the current location to the beginning of the file.
Pause | Pauses the action, remaining at the current location in the file.
get_MediaState | Gets the current state of the file terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITMediaControl::Pause

[This is preliminary documentation and subject to change.]

The Pause method pauses the action, remaining at the current location in the file.

HRESULT Pause( );

Parameters

This method has no parameters.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaControl, Stop


ITMediaControl::Start

[This is preliminary documentation and subject to change.]

The Start method starts the action at the current location.

HRESULT Start( );

Parameters

This method has no parameters.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaControl, Stop


ITMediaControl::Stop

[This is preliminary documentation and subject to change.]

The Stop method stops the current action and sets the current location to the beginning of the file.

HRESULT Stop( );

Parameters

This method has no parameters.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaControl, Start


ITMediaControl::get_MediaState

[This is preliminary documentation and subject to change.]

The get_MediaState method gets the current state of media on the file terminal.

HRESULT get_MediaState(
  TERMINAL_MEDIA_STATE * pTerminalMediaState
);

Parameters

pTerminalMediaState
[out,retval] Pointer to the TERMINAL_MEDIA_STATE descriptor of the current state of the file terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaControl, TERMINAL_MEDIA_STATE


ITMediaPlayback

[This is preliminary documentation and subject to change.]

The ITMediaPlayback interface provides playback-specific methods that allow an application to set and get the list of files to play.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITMediaPlayback methods | Description
put_PlayList | Sets the list of files to play.
get_PlayList | Gets the list of files to play.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaRecord


ITMediaPlayback::get_PlayList

[This is preliminary documentation and subject to change.]

The get_PlayList method gets the list of files and IStorage objects to play.

HRESULT get_PlayList(
  VARIANTARG * pPlayListVariant
);

Parameters

pPlayListVariant
[out,retval] Pointer to variant of type VT_ARRAY, which contains variants of type VT_BSTR and VT_STORAGE.

The VT_BSTR elements of the array contain the names of the files to play. The file extension is used to specify the type of file. Currently, supported file extensions are .avi, .asf, and .wav.

The VT_STORAGE elements of the array contain pointers to the IStorage interface of the object to use as the data source.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaPlayback, put_PlayList


ITMediaPlayback::put_PlayList

[This is preliminary documentation and subject to change.]

The put_PlayList method provides the file playback terminal with the list of files and IStorage objects to play.

HRESULT put_PlayList(
  VARIANTARG PlayListVariant
);

Parameters

PlayListVariant
[in] Variant of type VT_ARRAY, which contains variants of type VT_BSTR and VT_STORAGE.

The VT_BSTR elements of the array contain the names of the files to play. The file extension is used to determine the type of file. Currently, the supported file extensions are .avi, .asf, and .wav.

The VT_STORAGE elements of the array contain pointers to the IStorage interface of the object to use as the data source.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaPlayback, get_PlayList


ITMediaRecord

[This is preliminary documentation and subject to change.]

The ITMediaRecord interface provides recording-specific methods that allow an application to set and get the names of files to record.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITMediaRecord methods | Description
put_FileName | Sets the name of the file to record.
get_FileName | Gets the name of the file used for recording.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaPlayback


ITMediaRecord::get_FileName

[This is preliminary documentation and subject to change.]

The get_FileName method retrieves the name of the file that was used for recording by this terminal.

HRESULT get_FileName(
  BSTR * pbstrFileName
);

Parameters

pbstrFileName
[out,retval] The BSTR representation of the file name. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaRecord, put_FileName


ITMediaRecord::put_FileName

[This is preliminary documentation and subject to change.]

The put_FileName method sets the name of the file to record.

HRESULT put_FileName(
  BSTR bstrFileName,
  BOOL bAppendIfExists
);

Parameters

bstrFileName
[in] The BSTR representation of the file name.
bAppendIfExists
[in] If this flag is set to TRUE, and a file with this name already exists, the new data will be appended to the file. If this flag is set to FALSE, and the file exists, the new data will overwrite the old data.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaRecord, get_FileName


ITMediaSupport

The ITMediaSupport interface provides methods that allow an application to discover the media support capabilities for an Address Object that exposes this interface. A pointer to this interface can be obtained by calling QueryInterface using any address interface pointer, such as ITAddress.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITMediaSupport methods | Description
get_MediaTypes | Gets media types supported.
QueryMediaType | Indicates whether a given media type is supported.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAddress, ITTerminal, ITTerminalSupport, Address Object


ITMediaSupport::QueryMediaType

The QueryMediaType method indicates whether the service provider associated with the current address supports the media type or types indicated by lMediaType.

HRESULT QueryMediaType(
  long lMediaType,
  VARIANT_BOOL *pfSupport
);

Parameters

lMediaType
[in] Media type or types being queried.
pfSupport
[out, retval] Pointer to a VARIANT_BOOL indicating whether the media type is supported. If the returned value is VARIANT_TRUE, the media is supported; if it is VARIANT_FALSE, the media is not supported.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pfSupport parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaSupport, Address Object


ITMediaSupport::get_MediaTypes

The get_MediaTypes method gets the media type or types supported on the current address.

HRESULT get_MediaTypes(
  long *plMediaTypes
);

Parameters

plMediaTypes
[out, retval] Pointer to bitmask of ORed of media type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plMediaTypes parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMediaSupport, Address Object


ITMultiTrackTerminal

[This is preliminary documentation and subject to change.]

This ITMultiTrackTerminal interface is exposed on all multitrack terminals. The interface includes methods for enumerating, creating, and removing tracks.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITMultiTrackTerminal methods | Description
get_TrackTerminals | Creates and returns a collection containing the terminals contained by the multitrack terminal on which this method was called.
EnumerateTrackTerminals | Creates and returns an enumeration containing the terminals contained by the multitrack terminal on which this method was called.
CreateTrackTerminal | Creates a multitrack terminal that can handle a given media type or types and media direction.
get_MediaTypesInUse | Returns the media types of all tracks managed currently by the multitrack terminal.
get_DirectionsInUse | Returns the direction of all tracks managed currently by the multitrack terminal.
RemoveTrackTerminal | Removes the specified terminal from the collection of track terminals that belong to the multitrack terminal on which the function was called.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITMultiTrackTerminal::CreateTrackTerminal

[This is preliminary documentation and subject to change.]

The CreateTrackTerminal method creates a multitrack terminal that can handle a given media type or types and media direction.

HRESULT CreateTrackTerminal(
  long MediaType,
  TERMINAL_DIRECTION TerminalDirection,
  ITTerminal ** ppTerminal
);

Parameters

MediaType
[in] Bitwise ORed list of media types required for the terminal.
TerminalDirection
[in] The TERMINAL_DIRECTION descriptor for the terminal.
ppTerminal
[out,retval] Pointer to the ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMultiTrackTerminal, ITTerminal


ITMultiTrackTerminal::EnumerateTrackTerminals

[This is preliminary documentation and subject to change.]

The EnumerateTrackTerminals method creates and returns an enumeration containing the terminals contained by the multitrack terminal on which this method was called.

HRESULT EnumerateTrackTerminals(
  IEnumTerminal ** ppEnumTerminal
);

Parameters

ppEnumTerminal
[out,retval] Pointer to the IEnumTerminal interface enumerating terminals contained in the multitrack terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTerminalEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMultiTrackTerminal


ITMultiTrackTerminal::RemoveTrackTerminal

[This is preliminary documentation and subject to change.]

The RemoveTrackTerminal method removes the specified terminal from the collection of track terminals that belong to the multitrack terminal on which the method was called. If the track terminal has been selected on a stream, it should be unselected first.

HRESULT RemoveTrackTerminal(
  ITTerminal * pTrackTerminalToRemove
);

Parameters

pTrackTerminalToRemove
[in] Pointer to the ITTerminal interface of the terminal to remove.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTrackTerminalToRemove parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The primary use of the RemoveTrackTerminal method is cleanup during the terminal selection process. For example, if a track has been created, but it has not been selected on a stream, this method can be used to remove the track.

The actual action performed by this method may vary in the actual implementation of the terminal. For instance, calling this method on a File Recording Terminal causes the corresponding file data stream to be removed from the file. Calling this method on a File Playback Terminal fails because its set of terminals is determined solely by file configuration and cannot be changed by the caller.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMultiTrackTerminal, ITTerminal


ITMultiTrackTerminal::get_DirectionsInUse

[This is preliminary documentation and subject to change.]

The get_DirectionsInUse method returns the direction of all tracks managed currently by the multitrack terminal. For tracks that are multitrack terminals themselves, this method calls the track's ITMultiTrackTerminal::get_DirectionsInUse method to determine the track's directions.

HRESULT get_DirectionsInUse(
  TERMINAL_DIRECTION * plDirectionsInUsed
);

Parameters

plDirectionsInUsed
[out,retval] Pointer to the TERMINAL_DIRECTION descriptor of the directions.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMultiTrackTerminal


ITMultiTrackTerminal::get_MediaTypesInUse

[This is preliminary documentation and subject to change.]

The get_MediaTypesInUse method returns the media types (bitwise ORed) of all tracks managed currently by the multitrack terminal. For tracks that are multitrack terminals themselves, this method calls the track's ITMultiTrackTerminal::get_MediaTypesInUse method to determine the track's media types.

HRESULT get_MediaTypesInUse(
  long * plMediaTypesInUse
);

Parameters

plMediaTypesInUse
[out,retval] Bitwise ORed list of media types in use.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMultiTrackTerminal


ITMultiTrackTerminal::get_TrackTerminals

[This is preliminary documentation and subject to change.]

The get_TrackTerminals method creates and returns a collection containing the terminals contained by the multitrack terminal on which this method was called. The variant returned contains a pointer to an ITCollection interface that can be used to iterate through elements of type IEnumVARIANT. The elements of the collection contain pointers to tracks.

HRESULT get_TrackTerminals(
  VARIANT * pVariant
);

Parameters

pVariant
[out,retval] Pointer to a VARIANT containing an ITCollection of ITTerminal interface pointers for the tracks available.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | The pVariant parameter was not empty.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITMultiTrackTerminal, ITCollection, ITTerminal


ITParticipant

The ITParticipant interface is implemented by the IPConf MSP. It allows an application to retrieve information on conference participants, and get pointers to the streams associated with those participants.

This interface is exposed on the call object when a call uses the IP Conferencing. A pointer can be obtained by calling QueryInterface using an ITCallInfo pointer.

Methods in Vtable Order

IUnknown Methods

ITParticipant methods | Description
get_ParticipantTypedInfo | Gets a BSTR representation of the needed type of information, such as PTI_EMAILADDRESS.
get_MediaTypes | Gets the media types associated with a participant.
put_Status | Sets whether a stream associated with the participant is enabled.
get_Status | Gets the status of the participant.
get_Streams | Creates a collection of streams associated with the current participant. Provided for Automation client applications, such as those written in Visual Basic.
EnumerateStreams | Enumerates streams associated with the current participant.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

IPConf MSP, IPConf MSP Interfaces, ITCallInfo


ITParticipant::EnumerateStreams

The EnumerateStreams method enumerates streams currently with the participants. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Streams method.

HRESULT EnumerateStreams(
  IEnumStream **ppEnumStream
);

Parameters

ppEnumStream
[out, retval] Pointer to IEnumStream interface pointer.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumStream parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, get_Streams, IEnumStream


ITParticipant::get_MediaTypes

The get_MediaTypes method gets the media types associated with a participant.

HRESULT get_MediaTypes(
  long *plMediaType
);

Parameters

plMediaType
[out, retval] Pointer to media type flags, such as TAPIMEDIATYPE_VIDEO.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plMediaType parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, media types


ITParticipant::get_ParticipantTypedInfo

The get_ParticipantTypedInfo method gets a BSTR representation of the type of information needed, such as PTI_EMAILADDRESS.

HRESULT get_ParticipantTypedInfo(
  PARTICIPANT_TYPED_INFO InfoType,
  BSTR *ppInfo
);

Parameters

InfoType
[in] PARTICIPANT_TYPED_INFO descriptor of the type of information needed.
ppInfo
[out, retval] Pointer to BSTR representation of the information needed.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Storage of information into ppInfo failed.
E_INVALIDARG | The InfoType parameter is not valid.
E_POINTER | The ppInfo parameter is not a valid pointer.
TAPI_E_NOITEM | TAPI has no information on the specified type.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppInfo parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, PARTICIPANT_TYPED_INFO, media types


ITParticipant::get_Status

The get_Status method returns a VARIANT_BOOL indicating participant status.

HRESULT get_Status(
  ITStream *pITStream,
  VARIANT_BOOL *pStatus
);

Parameters

pITStream
[in] Pointer to ITStream interface.
pStatus
[out, retval] VARIANT_TRUE if the participant is enabled on the stream, VARIANT_FALSE if it is disabled.

Remarks

Enabling or disabling a participant's status on a stream allows an application to essentially mute a given participant.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pITStream parameter is not a valid pointer.
E_INVALIDARG | The pITStream parameter does not point to a valid interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, ITStream, put_Status


ITParticipant::get_Streams

The get_Streams method creates a collection of streams associated with the current participant. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateStreams method.

HRESULT get_Streams(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITStream interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, EnumerateStreams, IEnumStream, ITCollection, ITStream


ITParticipant::put_Status

The put_Status method sets the status of a participant.

HRESULT put_Status(
  ITStream *pITStream,
  VARIANT_BOOL fEnable
);

Parameters

pITStream
[in] Pointer to ITStream interface.
fEnable
[in] VARIANT_TRUE if the participant is enabled on the stream, VARIANT_FALSE if it is to be disabled.

Remarks

Enabling or disabling a participant's status on a stream allows an application to essentially mute a given participant.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_POINTER | The pITStream parameter is not a valid pointer.
E_INVALIDARG | The pITStream parameter does not point to a valid interface.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, ITStream, get_Status


ITParticipantControl

The ITParticipantControl interface is implemented by the IPConf MSP. This interface is exposed on the call object. This interface allows an application to retrieve pointers to the participants in a conference.

Methods in Vtable Order

ITParticipantControl methods | Description
EnumerateParticipants | Enumerates participants currently involved in the conference.
get_Participants | Creates a collection of participants associated with the current conference. Provided for Automation client applications, such as those written in Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.


ITParticipantControl::EnumerateParticipants

The EnumerateParticipants method enumerates participants associated with the current conference. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Participants method.

HRESULT EnumerateParticipants(
  IEnumParticipant **ppEnumParticipants
);

Parameters

ppEnumParticipants
[out, retval] Pointer to IEnumParticipant interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumParticipants parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantControl, get_Participants, IEnumParticipant, ITParticipant


ITParticipantControl::get_Participants

The get_Participants method creates a collection of participants associated with the current conference. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateParticipants method.

HRESULT get_Participants(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITParticipant interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantControl, EnumerateParticipants, ITCollection, ITParticipant


ITParticipantEvent

The ITParticipantEvent interface contains methods that retrieve the description of participant events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_PRIVATE, the method's pEvent parameter is an IDispatch pointer for the ITParticipantEvent interface. The methods of this interface can be used to retrieve information concerning a participant change that has occurred.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_PRIVATE event to enable reception of participant events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

ITParticipantEvent methods | Description
get_Event | Gets the PARTICIPANT_EVENT descriptor of the event.
get_Participant | Gets a pointer to an array of ITParticipant interfaces representing the participants involved in the event.
get_SubStream | Gets a pointer to an array of ITSubStream interfaces representing the substreams involved in the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, ITSubStream, ITCallInfo, PARTICIPANT_EVENT, ITTAPIEventNotification::Event, TAPI_EVENT, Register Events code snippet


ITParticipantEvent::get_Event

The get_Event method gets a PARTICIPANT_EVENT descriptor of the type of event that has occurred.

HRESULT get_Event(
  PARTICIPANT_EVENT *pParticipantEvent
);

Parameters

pParticipantEvent
[out, retval] Pointer to a PARTICIPANT_EVENT descriptor of the event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pParticipantEvent parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantEvent, PARTICIPANT_EVENT


ITParticipantEvent::get_Participant

The get_Participant method gets a pointer to an array of ITParticipant interfaces representing the participants involved in the event.

HRESULT get_Participant(
  ITParticipant **ppParticipant
);

Parameters

ppParticipant
[out, retval] Pointer to array of ITParticipant interfaces.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_NOITEMS | There are no participants associated with the event.
E_POINTER | The ppParticipant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantEvent, ITParticipant


ITParticipantEvent::get_SubStream

The get_SubStream gets a pointer to an array of ITSubStream interfaces representing the substreams involved in the event.

HRESULT get_SubStream(
  ITSubStream **ppSubStream
);

Parameters

ppSubStream
[out, retval] Pointer to array of ITSubStream pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_NOITEMS | There are no substreams associated with the event.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppSubStream parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantEvent, ITSubStream


ITParticipantSubStreamControl

The ITParticipantSubStreamControl interface is implemented by the IPConf MSP. This interface is exposed on the call object. This interface provides methods that allow an application to either discover or control the matching of substream to participant.

Methods in Vtable Order

ITParticipantSubStreamControl methods | Description
get_SubStreamFromParticipant | Gets substreams associated with a given participant.
get_ParticipantFromSubStream | Gets participants associated with a given substream.
SwitchTerminalToSubStream | Sets a participant on a substream.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipant, ITSubStream


ITParticipantSubStreamControl::SwitchTerminalToSubStream

The SwitchTerminalToSubStream method sets a terminal to the participant substream.

HRESULT SwitchTerminalToSubStream(
  ITTerminal *pITTerminal,
  ITSubStream *pITSubStream
);

Parameters

pITTerminal
[in] Pointer to ITTerminal interface.
pITSubStream
[in] Pointer to ITSubStream interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_UNEXPECTED | Participant information for the stream could not be accessed.
E_INVALIDARG | The pParticipant or the pITSubStream parameter does not point to a valid interface.
TAPI_E_NOITEMS | The substream is not ready.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantSubStreamControl, ITParticipant, ITSubStream, ITTerminal


ITParticipantSubStreamControl::get_ParticipantFromSubStream

The get_ParticipantFromSubStream method allows an application to discover which participants are associated with a given substream.

HRESULT get_ParticipantFromSubStream(
  ITSubStream *pITSubStream,
  ITParticipant **ppParticipant
);

Parameters

pITSubStream
[in] Pointer to ITSubStream interface.
ppParticipant
[out, retval] Pointer to array of ITParticipant interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pITSubStream or ppParticipant parameter is not a valid pointer.
E_INVALIDARG | The pITSubStream parameter does not point to valid interface.
TAPI_E_NOITEMS | There are no participants associated with the substream.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantSubStreamControl, ITParticipant, ITSubStream


ITParticipantSubStreamControl::get_SubStreamFromParticipant

The get_SubStreamFromParticipant method allows an application to discover which substreams are associated with a given participant.

HRESULT get_SubStreamFromParticipant(
  ITParticipant *pParticipant,
  ITSubStream **ppITSubStream
);

Parameters

pParticipant
[in] Pointer to ITParticipant interface.
ppITSubStream
[out, retval] Pointer to array of ITParticipant interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppITSubStream parameter is not a valid pointer.
E_INVALIDARG | The pParticipant parameter does not point to a valid interface.
E_UNEXPECTED | The stream's participant information could not be accessed.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Confpriv.h.
Library: Use Uuid.lib.

See Also

ITParticipantSubStreamControl, ITParticipant, ITSubStream


ITPhone

[This is preliminary documentation and subject to change.]

The ITPhone interface is the main interface for the new Phone objects in the TAPI 3.1 object model. This interface allows access to the phone device at a level comparable to that available with the TAPI 2.x C API. The interface also allows the application to determine which addresses the phone is usable on, and to get a list of terminals associated with the phone.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPhone methods | Description
Open | Opens the phone device.
Close | Closes the phone device.
get_Addresses | Gets the collection of addresses on which the phone can be used. For Visual Basic and scripting applications.
EnumerateAddresses | Enumerates the addresses on which the phone can be used. For C/C++ applications.
get_PhoneCapsLong | Gets a capability of the phone, based on the PHONECAPS_LONG enum passed in.
get_PhoneCapsString | Gets a string capability/information about the phone, based on the PHONECAPS_STRING enum passed in.
get_Terminals | Gets a collection of terminals that are associated with the phone.
EnumerateTerminals | Gets an enumeration of terminals that are associated with the phone.
get_ButtonMode | Gets the button mode associated with a particular button.
put_ButtonMode | Sets the button mode.
get_ButtonFunction | Gets the button function associated with a particular button.
put_ButtonFunction | Puts the button function.
get_ButtonText | Gets the button text associated with a particular button.
put_ButtonText | Sets the button text.
get_ButtonState | Gets the button state associated with a particular button.
get_HookSwitchState | Gets the current hookswitch state for a particular hookswitch device on the phone.
put_HookSwitchState | Sets the current hookswitch state for a particular hookswitch device on the phone.
put_RingMode | Sets the phone's ring mode.
get_RingMode | Gets the phone's ring mode.
put_RingVolume | Sets the phone's volume.
get_RingVolume | Gets the phone's volume.
get_Privilege | Gets the privilege of the open phone.
GetPhoneCapsBuffer | Gets a buffer capability/information about the phone, based on the PHONECAPS_BUFFER enum passed in. For C/C++ applications.
get_PhoneCapsBuffer | Gets a buffer capability/information about the phone, based on the PHONECAPS_BUFFER enum passed in. For Visual Basic and scripting applications.
get_LampMode | Gets the current lamp mode for the given lamp.
put_LampMode | Sets the current lamp mode for the given lamp.
get_Display | Gets the display for the phone.
SetDisplay | Sets the display for the phone.
EnumeratePreferredAddresses | Enumerates addresses that the phone is preferred for use on. For C/C++ applications.
get_PreferredAddresses | Returns a collection of addresses that the phone is preferred for use on. For Visual Basic and scripting applications.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITPhone::Close

[This is preliminary documentation and subject to change.]

The Close method closes this phone device. The phone device remains closed until the application calls the ITPhone::Open method. For more information, see the following Remarks section.

This method is analogous to the TAPI 2.x phoneOpen function; please see the TAPI 2.x documentation for more information.

HRESULT Close( );

Parameters

This method has no parameters.

Remarks

While a phone is closed, the application does not receive events pertaining to the phone.

A phone must be open with owner privilege for the application to set the state of the phone. Querying the state of the phone can typically be done even if the phone is not open; for more details, see the individual methods of the ITPhone interface.

After the phone device has been successfully closed, any ITAutomatedPhoneControl interface pointer obtained for this phone object is no longer valid.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone


ITPhone::EnumerateAddresses

[This is preliminary documentation and subject to change.]

The EnumerateAddresses method enumerates the addresses that the phone can be used on. The application does not have to call ITPhone::Open before executing this method.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_Addresses method.

HRESULT EnumerateAddresses(
  IEnumAddress ** ppEnumAddress
);

Parameters

ppEnumAddress
[out,retval] Pointer to the IEnumAddress interface.

Remarks

If no phones are available for use with the address, this method produces an empty enumeration and returns S_OK.

A phone device declares itself as being available on all addresses that support audio terminals by the TSP setting the PHONEFEATURE_GENERICPHONE bit in the dwPhoneFeatures member of the PHONECAPS structure. A phone device can also declare itself as being preferred to an address or set of addresses by returning address/line IDs using phoneGetID with device class tapi/line. The EnumerateAddresses method returns addresses that have been identified both ways.

To get only addresses that the phone is preferred on, you can call the EnumeratePreferredAddresses method.

A phone device declares itself as being specific to an address or set of addresses by returning address/line IDs using phoneGetID with device class tapi/line. Although the phoneGetID function requires the handle to an open phone device, the application does not have to call the ITPhone::Open method before calling EnumerateAddresses. This is because the implementation of the phone object can open the phone and call phoneGetID during TAPI initialization or when a new phone object appears.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, EnumeratePreferredAddresses


ITPhone::EnumeratePreferredAddresses

[This is preliminary documentation and subject to change.]

The EnumeratePreferredAddresses method enumerates the preferred addresses for the phone object. The application does not have to call ITPhone::Open before executing this method.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_Addresses method.

HRESULT EnumeratePreferredAddresses(
  IEnumAddress ** ppEnumAddress
);

Parameters

ppEnumAddress
[out,retval] Pointer to a location where, on success, the method places a pointer to an enumeration object that contains the list of addresses. For more information, see the following Remarks section.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumAddress parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the enumeration object.

Remarks

If there are no usable addresses present on the system, this method produces an empty enumeration and returns S_OK.

A phone device declares itself as being preferred to an address or set of addresses by returning address/line IDs using the TAPI 2.x phoneGetID function with device class tapi/line.

Although the phoneGetID function requires the handle to an open phone device, the application does not have to call the ITPhone::Open method before calling EnumeratePreferredAddresses. This is because the implementation of the phone object can open the phone and call phoneGetID during TAPI initialization or when a new phone object appears.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, EnumerateAddresses


ITPhone::EnumerateTerminals

[This is preliminary documentation and subject to change.]

The EnumerateTerminals method retrieves an enumeration of terminals that are associated with the phone. The application does not have to call ITPhone::Open before executing this method.

HRESULT EnumerateTerminals(
  ITAddress * pAddress,
  IEnumTerminal ** ppEnumTerminal
);

Parameters

pAddress
[in] Pointer to ITAddress interface.
ppEnumTerminal
[out,retval] Pointer to the IEnumTerminal interface that enumerates terminals.

Remarks

If no terminals are associated with the phone, this method produces an empty enumeration and returns S_OK.

Although the phoneGetID function requires the handle to an open phone device, the application does not have to call the ITPhone::Open method before calling EnumerateTerminals. This is because the implementation of the phone object can open the phone and call phoneGetID during TAPI initialization or when a new phone object appears.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, ITAddress, IEnumTerminal


ITPhone::GetPhoneCapsBuffer

[This is preliminary documentation and subject to change.]

The GetPhoneCapsBuffer method gets a buffer capability/information about the phone, based on the PHONECAPS_BUFFER enum passed in.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_PhoneCapsBuffer method.

HRESULT GetPhoneCapsBuffer(
  PHONECAPS_BUFFER pcbCaps,
  DWORD * pdwSize,
  BYTE ** ppPhoneCapsBuffer
);

Parameters

pcbCaps
[in] The PHONECAPS_BUFFER descriptor for the phone capability.
pdwSize
[out] Size of the buffer, in bytes.
ppPhoneCapsBuffer
[out] Pointer to the buffer containing the values.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, PHONECAPS


ITPhone::get_PreferredAddresses

[This is preliminary documentation and subject to change.]

The get_PreferredAddresses method returns a collection of addresses that the phone is preferred for use on. The application does not have to call ITPhone::Open before executing this method.

This method is intended for Visual Basic and scripting applications. C/C++ applications will find it more convenient to use the EnumerateAddresses method.

HRESULT get_PreferredAddresses(
  VARIANT * pAddresses
);

Parameters

pAddresses
[out,retval] Pointer to a VARIANT containing an ITCollection of ITAddress interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pAddresses parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the collection object.

Remarks

If no usable addresses are present on the system, this method returns an empty collection.

A phone device declares itself as being preferred to an address or set of addresses by returning address/line IDs using the TAPI 2.x phoneGetID function with device class tapi/line.

Although the phoneGetID function requires the handle to an open phone device, the application does not have to call the ITPhone::Open method before calling EnumeratePreferredAddresses. This is because the implementation of the phone object can open the phone and call phoneGetID during TAPI initialization or when a new phone object appears.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_Addresses


ITPhone::Open

[This is preliminary documentation and subject to change.]

The Open method opens this phone device. The phone device remains open until the application calls ITPhone::Close or until TAPI is shut down.

This method is analogous to the TAPI 2.x phoneOpen function; please see theTAPI 2.x documentation for more information.

HRESULT Open(
  PHONE_PRIVILEGE Privilege
);

Parameters

Privilege
[in] The PHONE_PRIVILEGE descriptor for the application's privilege status with respect to the phone device.

Remarks

While a phone is open, the application receives events pertaining to the phone.

Also, a phone must be open with owner privilege for the application to set the state of the phone. Querying the state of the phone can typically be done even if the phone is not open; for more details, see the individual methods of the ITPhone interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone


ITPhone::SetDisplay

[This is preliminary documentation and subject to change.]

The SetDisplay method sets what will appear in a given row and column of the phone's display.

HRESULT SetDisplay(
  long lRow,
  long lColumn,
  BSTR bstrDisplay
);

Parameters

lRow
[in] Display row.
lColumn
[in] Display column.
bstrDisplay
[in] The BSTR representation of the value to display.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_Display


ITPhone::get_Addresses

[This is preliminary documentation and subject to change.]

The get_Addresses method returns a collection of addresses that the phone can be used on. The application does not have to call ITPhone::Open before executing this method.

This method is intended for Visual Basic and scripting applications. C/C++ applications should use the EnumerateAddresses method instead.

HRESULT get_Addresses(
  VARIANT * pAddresses
);

Parameters

pAddresses
[out,retval] Pointer to a VARIANT containing an ITCollection of ITAddress interface pointers.

Remarks

A phone device declares itself as being available on all addresses that support audio terminals by the TSP setting the PHONEFEATURE_GENERICPHONE bit in the dwPhoneFeatures member of the PHONECAPS structure. A phone device can also declare itself as being preferred to an address or set of addresses by returning address/line IDs using phoneGetID with device class tapi/line. The get_Addresses method returns addresses that have been identified both ways.

To get only addresses that the phone is preferred on, you can call the get_PreferredAddresses method.

The application does not have to call the ITPhone::Open method before calling get_Addresses. This is because the implementation of the phone object can open the phone and call phoneGetID during TAPI initialization or when a new phone object appears.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_PreferredAddresses


ITPhone::get_ButtonFunction

[This is preliminary documentation and subject to change.]

The get_ButtonFunction method retrieves the button function associated with a particular button.

The application must call the ITPhone::Open method before invoking this method; otherwise, the method fails.

HRESULT get_ButtonFunction(
  long lButtonID,
  PHONE_BUTTON_FUNCTION * pButtonFunction
);

Parameters

lButtonID
[in] Button identifier.
pButtonFunction
[out,retval] The PHONE_BUTTON_FUNCTION descriptor for the button's function.

Remarks

See the description of the PHONE_BUTTON_FUNCTION enum for a list of possible button functions.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, put_ButtonFunction


ITPhone::get_ButtonMode

[This is preliminary documentation and subject to change.]

The get_ButtonMode method retrieves the button mode associated with a particular button.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT get_ButtonMode(
  long lButtonID,
  PHONE_BUTTON_MODE * pButtonMode
);

Parameters

lButtonID
[in] Button identifier. For more information, see the following Remarks section.
pButtonMode
[out,retval] The PHONE_BUTTON_MODE descriptor for the button's mode.

Remarks

See the description of the PHONE_BUTTON_MODE enum and the TAPI 2.x documentation for more information about button modes.

The two following PHONE_BUTTON_MODE values are of particular interest:

  1. If the PHONE_BUTTON_MODE value is PBM_FEATURE, the application should call the get_ButtonFunction to retrieve the specific meaning of the button.
  2. If the PHONE_BUTTON_MODE value is PBM_KEYPAD, the button is a keypad button whose value is indicated by the value of the lButtonID parameter. For example, if lButtonID == 10 then the button is the * (star) key on the keypad.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_ButtonFunction, put_ButtonMode


ITPhone::get_ButtonState

[This is preliminary documentation and subject to change.]

The get_ButtonState method retrieves the button state associated with a particular button.

The application must call the ITPhone::Open method before invoking this method; otherwise, the invocation fails.

HRESULT get_ButtonState(
  long lButtonID,
  PHONE_BUTTON_STATE * pButtonState
);

Parameters

lButtonID
[in] Button identifier.
pButtonState
[out,retval] The PHONE_BUTTON_STATE descriptor for the button's state.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, ITPhoneEvent::get_ButtonState


ITPhone::get_ButtonText

[This is preliminary documentation and subject to change.]

The get_ButtonText method retrieves the button text associated with a particular button.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails. See the TAPI 2.x documentation for more information about the concept of button text.

HRESULT get_ButtonText(
  long lButtonID,
  BSTR * ppButtonText
);

Parameters

lButtonID
[in] Button identifier.
ppButtonText
[out,retval] The BSTR representation of the button text. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, put_ButtonText


ITPhone::get_Display

[This is preliminary documentation and subject to change.]

The get_Display method gets the display for the phone. In TAPI, the display is simply an NxM character buffer.

HRESULT get_Display(
  BSTR * pbstrDisplay
);

Parameters

pbstrDisplay
[out,retval] The BSTR representation of the phone display. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, SetDisplay


ITPhone::get_HookSwitchState

[This is preliminary documentation and subject to change.]

The get_HookSwitchState method retrieves the current hookswitch state for a particular hookswitch device on the phone.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT get_HookSwitchState(
  PHONE_HOOK_SWITCH_DEVICE HookSwitchDevice,
  PHONE_HOOK_SWITCH_STATE * pHookSwitchState
);

Parameters

HookSwitchDevice
[in] The PHONE_HOOK_SWITCH_DEVICE descriptor for the hookswitch type.
pHookSwitchState
[out,retval] The PHONE_HOOK_SWITCH_STATE descriptor for the hookswitch status.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, put_HookSwitchState


ITPhone::get_LampMode

[This is preliminary documentation and subject to change.]

The get_LampMode method gets the current lamp mode for the given lamp.

HRESULT get_LampMode(
  long lLampID,
  PHONE_LAMP_MODE * pLampMode
);

Parameters

lLampID
[in] Lamp identifier.
pLampMode
[out,retval] The PHONE_LAMP_MODE descriptor for the phone's lamp status.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, put_LampMode


ITPhone::get_PhoneCapsBuffer

[This is preliminary documentation and subject to change.]

The get_PhoneCapsBuffer method gets a buffer capability/information about the phone, based on the PHONECAPS_BUFFER enum passed in.

This method is intended for Visual Basic and scripting applications. C/C++ applications must use the GetPhoneCapsBuffer method.

HRESULT get_PhoneCapsBuffer(
  PHONECAPS_BUFFER pcbCaps,
  VARIANT * pVarBuffer
);

Parameters

pcbCaps
[in] The PHONECAPS_BUFFER descriptor for the phone capability.
pVarBuffer
[out,retval] Pointer to VARIANT containing the capability value.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, PHONECAPS


ITPhone::get_PhoneCapsLong

[This is preliminary documentation and subject to change.]

The get_PhoneCapsLong method gets a DWORD capability of the phone, based on the PHONECAPS_LONG enum passed in. The application does not have to call ITPhone::Open before executing this method.

HRESULT get_PhoneCapsLong(
  PHONECAPS_LONG pclCap,
  long * plCapability
);

Parameters

pclCap
[in] The PHONECAPS_LONG descriptor for the phone capability.
plCapability
[out,retval] Capability value.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, PHONECAPS


ITPhone::get_PhoneCapsString

[This is preliminary documentation and subject to change.]

The get_PhoneCapsString method gets a string capability/information about the phone, based on the PHONECAPS_STRING enum passed in. The application does not have to call ITPhone::Open before executing this method.

HRESULT get_PhoneCapsString(
  PHONECAPS_STRING pcsCap,
  BSTR * ppCapability
);

Parameters

pcsCap
[in] The PHONECAPS_STRING descriptor for the phone capability.
ppCapability
[out,retval] Capability value. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, PHONECAPS


ITPhone::get_Privilege

[This is preliminary documentation and subject to change.]

The get_Privilege method retrieves the privilege of the open phone.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT get_Privilege(
  PHONE_PRIVILEGE * pPrivilege
);

Parameters

pPrivilege
[out,retval] The PHONE_PRIVILEGE descriptor for the application's privilege status with respect to the phone device.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone


ITPhone::get_RingMode

[This is preliminary documentation and subject to change.]

The get_RingMode method retrieves the current ring mode for the phone.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT get_RingMode(
  long * plRingMode
);

Parameters

plRingMode
[out,retval] Phone ring mode.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, put_RingMode


ITPhone::get_RingVolume

[This is preliminary documentation and subject to change.]

The get_RingVolume method retrieves the current ring volume for the phone.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT get_RingVolume(
  long * plRingVolume
);

Parameters

plRingVolume
[out,retval] Ring volume.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, put_RingVolume


ITPhone::get_Terminals

[This is preliminary documentation and subject to change.]

The get_Terminals method retrieves a collection of terminals that are associated with the phone. The application does not have to call ITPhone::Open before executing this method.

HRESULT get_Terminals(
  ITAddress * pAddress,
  VARIANT * pTerminals
);

Parameters

pAddress
[in] Pointer to the ITAddress interface.
pTerminals
[out,retval] Pointer to a VARIANT containing an ITCollection of ITTerminal interface pointers.

Remarks

If no terminals are associated with the phone, this method produces an empty collection and returns S_OK.

The application does not have to call the ITPhone::Open method before calling get_Terminals. This is because the implementation of the phone object can open the phone and call phoneGetID during TAPI initialization or when a new phone object appears.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, ITAddress, ITCollection, ITTerminal


ITPhone::put_ButtonFunction

[This is preliminary documentation and subject to change.]

The put_ButtonFunction method sets the button function.

HRESULT put_ButtonFunction(
  long lButtonID,
  PHONE_BUTTON_FUNCTION ButtonFunction
);

Parameters

lButtonID
[in] Button identifier.
ButtonFunction
[in] The PHONE_BUTTON_FUNCTION descriptor for the button's function.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_ButtonFunction


ITPhone::put_ButtonMode

[This is preliminary documentation and subject to change.]

The put_ButtonMode method sets the button mode.

HRESULT put_ButtonMode(
  long lButtonID,
  PHONE_BUTTON_MODE ButtonMode
);

Parameters

lButtonID
[in] Button identifier.
ButtonMode
[in] The PHONE_BUTTON_MODE descriptor for the button's mode.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_ButtonMode


ITPhone::put_ButtonText

[This is preliminary documentation and subject to change.]

The put_ButtonText method sets the button text.

HRESULT put_ButtonText(
  long lButtonID,
  BSTR bstrButtonText
);

Parameters

lButtonID
[in] Button identifier.
bstrButtonText
[in] The BSTR representation of the button text.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_ButtonText


ITPhone::put_HookSwitchState

[This is preliminary documentation and subject to change.]

The put_HookSwitchState method sets the current hookswitch state for a particular hookswitch device on the phone.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT put_HookSwitchState(
  PHONE_HOOK_SWITCH_DEVICE HookSwitchDevice,
  PHONE_HOOK_SWITCH_STATE HookSwitchState
);

Parameters

HookSwitchDevice
[in] The PHONE_HOOK_SWITCH_DEVICE descriptor for the hookswitch type.
HookSwitchState
[in] The PHONE_HOOK_SWITCH_STATE descriptor for the hookswitch status.

Remarks

Typically, speakerphones and headsets have application-settable hookswitch states, and handsets do not, but this feature is TSP-dependent.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_HookSwitchState


ITPhone::put_LampMode

[This is preliminary documentation and subject to change.]

The put_LampMode method sets the current lamp mode for the given lamp.

HRESULT put_LampMode(
  long lLampID,
  PHONE_LAMP_MODE LampMode
);

Parameters

lLampID
[in] Lamp identifier.
LampMode
[in] The PHONE_LAMP_MODE descriptor for the phone's lamp status.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_LampMode


ITPhone::put_RingMode

[This is preliminary documentation and subject to change.]

The put_RingMode method requests that the phone change its ring mode.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT put_RingMode(
  long lRingMode
);

Parameters

lRingMode
[in] Ring mode.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_RingMode


ITPhone::put_RingVolume

[This is preliminary documentation and subject to change.]

The put_RingVolume method requests that the phone change its ring volume.

The application must call ITPhone::Open before invoking this method; otherwise, the invocation fails.

HRESULT put_RingVolume(
  long lRingVolume
);

Parameters

lRingVolume
[in] Phone volume. For more information, see the following Remarks section.

Remarks

If the phone is currently ringing (RingMode != 0), the new volume takes effect immediately. If the phone is not currently ringing (RingMode == 0), the new volume takes effect the next time the phone rings.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhone, get_RingVolume


ITPhoneEvent

[This is preliminary documentation and subject to change.]

The ITPhoneEvent interface contains methods that retrieve the description of phone events that have occurred. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_PHONEEVENT, the method's pEvent parameter is an IDispatch pointer for the ITPhoneEvent interface.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes TE_PHONEEVENT to enable reception of phone events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPhoneEvent methods | Description
get_Phone | Gets a pointer to the ITPhone interface on the phone object that fired this event.
get_Event | Gets a PHONE_EVENT value specifying the type of phone event that occurred.
get_ButtonState | Gets a PHONE_BUTTON_STATE value specifying the state to which the button has transitioned.
get_HookSwitchState | Gets a PHONE_HOOK_SWITCH_STATE value specifying the state to which the hookswitch has transitioned.
get_HookSwitchDevice | Gets a PHONE_HOOK_SWITCH_DEVICE value specifying the hookswitch device that changed state.
get_RingMode | Gets a long value specifying the ring mode to which the phone has transitioned.
get_ButtonLampId | Gets a long value indicating which button or lamp triggered the event.
get_NumberGathered | Returns a BSTR value specifying the phone number that was gathered.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITPhoneEvent::get_ButtonLampId

[This is preliminary documentation and subject to change.]

The get_ButtonLampId method returns a long value indicating which button or lamp triggered the event. This information is available only when ITPhoneEvent::get_Event returns PE_LAMPMODE or PE_BUTTON.

HRESULT get_ButtonLampId(
  long * plButtonLampId
);

Parameters

plButtonLampId
[out,retval] Button or lamp ID.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent, ITPhoneEvent::get_Event


ITPhoneEvent::get_ButtonState

[This is preliminary documentation and subject to change.]

The get_ButtonState method returns a PHONE_BUTTON_STATE value specifying the state to which the button has transitioned. This information is available only when the ITPhoneEvent::get_Event method returns PE_BUTTON.

HRESULT get_ButtonState(
  PHONE_BUTTON_STATE * pState
);

Parameters

pState
[out,retval] Pointer to the PHONE_BUTTON_STATE descriptor of the button's current state.

Remarks

This method is available because some buttons do not support the PBS_DOWN button state, but instead momentarily report PBS_PRESSED. Additionally, the application can miss the button press on phones that do support PBS_DOWN if the button is pressed only for a short time and the call to the ITPhone::get_ButtonState method does not execute quickly enough.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent, ITPhoneEvent::get_Event


ITPhoneEvent::get_Event

[This is preliminary documentation and subject to change.]

The get_Event method returns a PHONE_EVENT value specifying the type of phone event that occurred.

HRESULT get_Event(
  PHONE_EVENT * pEvent
);

Parameters

pEvent
[out,retval] The PHONE_EVENT descriptor of the event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent


ITPhoneEvent::get_HookSwitchDevice

[This is preliminary documentation and subject to change.]

The get_HookSwitchDevice method returns a PHONE_HOOK_SWITCH_DEVICE value specifying the hookswitch device that changed state. This information is available only when the ITPhoneEvent::get_Event method returns PE_HOOKSWITCH.

HRESULT get_HookSwitchDevice(
  PHONE_HOOK_SWITCH_DEVICE * pDevice
);

Parameters

pDevice
[out,retval] Pointer to the PHONE_HOOK_SWITCH_DEVICE descriptor of the type of device that has changed hookswitch state.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent, ITPhoneEvent::get_Event


ITPhoneEvent::get_HookSwitchState

[This is preliminary documentation and subject to change.]

The get_HookSwitchState method returns a PHONE_HOOK_SWITCH_STATE value specifying the state to which the hookswitch has transitioned. This information is available only when the ITPhoneEvent::get_Event method returns PE_HOOKSWITCH.

HRESULT get_HookSwitchState(
  PHONE_HOOK_SWITCH_STATE * pState
);

Parameters

pState
[out,retval] Pointer to the PHONE_HOOK_SWITCH_STATE descriptor of the current hookswitch state.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent, ITPhoneEvent::get_Event


ITPhoneEvent::get_NumberGathered

[This is preliminary documentation and subject to change.]

The get_NumberGathered method returns a BSTR value specifying the phone number that was gathered. This information is available only when the ITPhoneEvent::get_Event method returns PE_NUMBERGATHERED.

HRESULT get_NumberGathered(
  BSTR * ppNumber
);

Parameters

ppNumber
[out,retval] Phone number that was gathered. The BSTR is allocated using SysAllocString and should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent, ITPhoneEvent::get_Event


ITPhoneEvent::get_Phone

[This is preliminary documentation and subject to change.]

The get_Phone method returns a pointer to the ITPhone interface on the phone object that fired this event.

HRESULT get_Phone(
  ITPhone ** ppPhone
);

Parameters

ppPhone
[out,retval] Pointer to the ITPhone interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent, ITPhone


ITPhoneEvent::get_RingMode

[This is preliminary documentation and subject to change.]

The get_RingMode method returns a long value specifying the ring mode to which the phone has transitioned. This information is available only when the ITPhoneEvent::get_Event method returns PE_RINGMODE.

HRESULT get_RingMode(
  long * plRingMode
);

Parameters

plRingMode
[out,retval] Ring mode.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPhoneEvent, ITPhoneEvent::get_Event


ITPluggableTerminalClassInfo

[This is preliminary documentation and subject to change.]

The ITPluggableTerminalClassInfo interface exposes methods that allow the application to retrieve information concerning a pluggable terminal.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPluggableTerminalClassInfo methods | Description
get_Name | Gets the terminal's friendly name.
get_Company | Gets the name of the company that issued this pluggable terminal.
get_Version | Gets the terminal version.
get_TerminalClass | Gets the terminal's terminal class.
get_CLSID | Gets the CLSID used to CoCreateInstance the terminal.
get_Direction | Gets the direction supported by the terminal.
get_MediaTypes | Gets the media types supported by the terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITPluggableTerminalClassInfo::get_CLSID

[This is preliminary documentation and subject to change.]

The get_CLSID method gets the CLSID used to CoCreateInstance the terminal.

HRESULT get_CLSID(
  BSTR * pCLSID
);

Parameters

pCLSID
[retval][out] The BSTR representation of the CLSID. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo


ITPluggableTerminalClassInfo::get_Company

[This is preliminary documentation and subject to change.]

The get_Company method gets the name of the company that issued this pluggable terminal.

HRESULT get_Company(
  BSTR * pCompany
);

Parameters

pCompany
[retval][out] The BSTR representation of the terminal's company name. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo


ITPluggableTerminalClassInfo::get_Direction

[This is preliminary documentation and subject to change.]

The get_Direction method gets the direction supported by the terminal.

HRESULT get_Direction(
  TERMINAL_DIRECTION * pDirection
);

Parameters

pDirection
[retval][out] The TERMINAL_DIRECTION descriptor for the direction supported by the terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo


ITPluggableTerminalClassInfo::get_MediaTypes

[This is preliminary documentation and subject to change.]

The get_MediaTypes method gets the media types supported by the terminal.

HRESULT get_MediaTypes(
  long * pMediaTypes
);

Parameters

pMediaTypes
[retval][out] Bitwise ORed list of media types supported by the terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo


ITPluggableTerminalClassInfo::get_Name

[This is preliminary documentation and subject to change.]

The get_Name method gets the terminal's friendly name.

HRESULT get_Name(
  BSTR * pName
);

Parameters

pName
[retval][out] The BSTR representation of the terminal's friendly name. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo


ITPluggableTerminalClassInfo::get_TerminalClass

[This is preliminary documentation and subject to change.]

The get_TerminalClass method gets the terminal's terminal class.

HRESULT get_TerminalClass(
  BSTR * pTerminalClass
);

Parameters

pTerminalClass
[retval][out] The BSTR representation of the terminal's terminal class. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo


ITPluggableTerminalClassInfo::get_Version

[This is preliminary documentation and subject to change.]

The get_Version method gets the terminal version.

HRESULT get_Version(
  BSTR * pVersion
);

Parameters

pVersion
[retval][out] The BSTR representation of the terminal version. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassInfo


ITPluggableTerminalClassRegistration

[This is preliminary documentation and subject to change.]

The ITPluggableTerminalClassRegistration interface exposes methods that allow the creation, modification, and deletion of the registry entry for a pluggable terminal. (Each pluggable terminal must register itself in order to make the terminal available to applications.)

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPluggableTerminalClassRegistration methods | Description
get_Name | Gets the terminal's friendly name.
put_Name | Sets the terminal's friendly name.
get_Company | Gets the name of the company that issued this pluggable terminal.
put_Company | Sets the name of the company that issued this pluggable terminal.
get_Version | Gets the terminal version.
put_Version | Sets the terminal version.
get_TerminalClass | Gets the terminal's terminal class.
put_TerminalClass | Sets the terminal's terminal class.
get_CLSID | Gets the CLSID used to CoCreateInstance the terminal.
put_CLSID | Sets the CLSID used to CoCreateInstance the terminal.
get_Direction | Gets the direction supported by the terminal.
put_Direction | Sets the direction supported by the terminal.
get_MediaTypes | Gets the media types supported by the terminal.
put_MediaTypes | Sets the media types supported by the terminal.
Add | Adds the terminal into the registry.
Delete | Deletes the terminal entry from the registry.
GetTerminalClassInfo | Gets all information from the registry for a specific terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.


ITPluggableTerminalClassRegistration::Add

[This is preliminary documentation and subject to change.]

The Add method adds terminal information to the registry. If an entry for the terminal already exists, the method edits the entry.

HRESULT Add(
  BSTR bstrSuperclass
);

Parameters

bstrSuperclass
[in] The BSTR representation of the CLSID for the terminal superclass.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, Delete


ITPluggableTerminalClassRegistration::Delete

[This is preliminary documentation and subject to change.]

The Delete method deletes the terminal class from the registry.

HRESULT Delete(
  BSTR bstrSuperclass
);

Parameters

bstrSuperclass
[in] The BSTR representation of the CLSID for the terminal superclass.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, Add


ITPluggableTerminalClassRegistration::GetTerminalClassInfo

[This is preliminary documentation and subject to change.]

The GetTerminalClassInfo method gets all the information from the registry for a specific terminal.

HRESULT GetTerminalClassInfo(
  BSTR bstrSuperclass
);

Parameters

bstrSuperclass
[in] The BSTR representation of the CLSID for the terminal superclass.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration


ITPluggableTerminalClassRegistration::get_CLSID

[This is preliminary documentation and subject to change.]

The get_CLSID method gets the CLSID used to CoCreateInstance the terminal.

HRESULT get_CLSID(
  BSTR * pCLSID
);

Parameters

pCLSID
[retval][out] The BSTR representation of the CLSID. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, put_CLSID


ITPluggableTerminalClassRegistration::get_Company

[This is preliminary documentation and subject to change.]

The get_Company method gets the name of the company that issued this pluggable terminal.

HRESULT get_Company(
  BSTR * pCompany
);

Parameters

pCompany
[retval][out] The BSTR representation of the terminal's company name. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, put_Company


ITPluggableTerminalClassRegistration::get_Direction

[This is preliminary documentation and subject to change.]

The get_Direction method gets the direction supported by the terminal.

HRESULT get_Direction(
  TMGR_DIRECTION * pDirection
);

Parameters

pDirection
[retval][out] The TMGR_DIRECTION descriptor of the terminal direction.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, put_Direction


ITPluggableTerminalClassRegistration::get_MediaTypes

[This is preliminary documentation and subject to change.]

The get_MediaTypes method gets the media types supported by the terminal.

HRESULT get_MediaTypes(
  long * pMediaTypes
);

Parameters

pMediaTypes
[retval][out] Bitwise ORed list of the media types supported by the terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, put_MediaTypes


ITPluggableTerminalClassRegistration::get_Name

[This is preliminary documentation and subject to change.]

The get_Name method gets the terminal's friendly name.

HRESULT get_Name(
  BSTR * pName
);

Parameters

pName
[retval][out] The BSTR representation of the friendly name. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, put_Name


ITPluggableTerminalClassRegistration::get_TerminalClass

[This is preliminary documentation and subject to change.]

The get_TerminalClass method gets the terminal's terminal class.

HRESULT get_TerminalClass(
  BSTR * pTerminalClass
);

Parameters

pTerminalClass
[retval][out] The BSTR representation of the terminal class. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, put_TerminalClass


ITPluggableTerminalClassRegistration::get_Version

[This is preliminary documentation and subject to change.]

The get_Version method gets the terminal version.

HRESULT get_Version(
  BSTR * pVersion
);

Parameters

pVersion
[retval][out] The BSTR representation of the terminal version. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, put_Version


ITPluggableTerminalClassRegistration::put_CLSID

[This is preliminary documentation and subject to change.]

The put_CLSID method sets the CLSID used to CoCreateInstance the terminal.

HRESULT put_CLSID(
  BSTR bstrCLSID
);

Parameters

bstrCLSID
[in] The BSTR representation of the CLSID.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, get_CLSID


ITPluggableTerminalClassRegistration::put_Company

[This is preliminary documentation and subject to change.]

The put_Company method sets the name of the company that issued this pluggable terminal.

HRESULT put_Company(
  BSTR bstrCompany
);

Parameters

bstrCompany
[in] The BSTR representation of the terminal's company name.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, get_Company


ITPluggableTerminalClassRegistration::put_Direction

[This is preliminary documentation and subject to change.]

The put_Direction method sets the direction supported by the terminal.

HRESULT put_Direction(
  TMGR_DIRECTION nDirection
);

Parameters

nDirection
[in] The TMGR_DIRECTION descriptor of the terminal direction.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, get_Direction


ITPluggableTerminalClassRegistration::put_MediaTypes

[This is preliminary documentation and subject to change.]

The put_MediaTypes method sets the media types supported by the terminal.

HRESULT put_MediaTypes(
  long nMediaTypes
);

Parameters

nMediaTypes
[in] Bitwise ORed list of the media types supported by the terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, get_MediaTypes


ITPluggableTerminalClassRegistration::put_Name

[This is preliminary documentation and subject to change.]

The put_Name method sets the name of the terminal class being registered.

HRESULT put_Name(
  BSTR bstrName
);

Parameters

bstrName
[in] The BSTR representation of the name.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, get_Name


ITPluggableTerminalClassRegistration::put_TerminalClass

[This is preliminary documentation and subject to change.]

The put_TerminalClass method sets the terminal's terminal class.

HRESULT put_TerminalClass(
  BSTR bstrTerminalClass
);

Parameters

bstrTerminalClass
[in] The BSTR representation of the terminal class.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, get_TerminalClass


ITPluggableTerminalClassRegistration::put_Version

[This is preliminary documentation and subject to change.]

The put_Version method sets the terminal version.

HRESULT put_Version(
  BSTR bstrVersion
);

Parameters

bstrVersion
[in] The BSTR representation of the terminal version.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalClassRegistration, get_Version


ITPluggableTerminalEventSink

[This is preliminary documentation and subject to change.]

The ITPluggableTerminalEventSink interface provides a method that fires a message to notify client applications about a change in a pluggable terminal.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPluggableTerminalEventSink methods | Description
FireEvent | Notifies the client application of a change in the pluggable terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalEventSinkRegistration


ITPluggableTerminalEventSink::FireEvent

[This is preliminary documentation and subject to change.]

The FireEvent method results in a message that notifies the client application of a change in the pluggable terminal. For example, if the terminal is no longer available, the event member of the MSP_EVENT_INFO structure is set to ME_ADDRESS_EVENT and the type member is set to ADDRESS_TERMINAL_UNAVAILABLE.

HRESULT FireEvent(
  const MSP_EVENT_INFO * pMspEventInfo
);

Parameters

pMspEventInfo
[in] Pointer to a const cast of the MSP_EVENT_INFO structure.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalEventSink, MSP_EVENT_INFO


ITPluggableTerminalEventSinkRegistration

[This is preliminary documentation and subject to change.]

The ITPluggableTerminalEventSinkRegistration interface registers and unregisters a client application for pluggable terminal events.

Methods in Vtable Order

ITPluggableTerminalEventSinkRegistration methods | Description
RegisterSink | Register for pluggable terminal events.
UnregisterSink | Unregister for pluggable terminal events.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalEventSink


ITPluggableTerminalEventSinkRegistration::RegisterSink

[This is preliminary documentation and subject to change.]

The RegisterSink method registers the application for pluggable terminal event notification.

HRESULT RegisterSink(
  ITPluggableTerminalEventSink * pEventSink
);

Parameters

pEventSink
[in] Pointer to the ITPluggableTerminalEventSink interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalEventSinkRegistration, ITPluggableTerminalEventSink, UnregisterSink


ITPluggableTerminalEventSinkRegistration::UnregisterSink

[This is preliminary documentation and subject to change.]

The UnregisterSink method clears event registration for pluggable terminal events.

HRESULT UnregisterSink( );

Parameters

This method has no parameters.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalEventSinkRegistration, RegisterSink


ITPluggableTerminalInitialization

[This is preliminary documentation and subject to change.]

The ITPluggableTerminalInitialization interface is implemented by pluggable terminals and allows the Terminal Manager to initialize the terminal.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPluggableTerminalInitialization methods | Description
InitializeDynamic | Performs primary terminal object creation for the pluggable terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.


ITPluggableTerminalInitialization::InitializeDynamic

[This is preliminary documentation and subject to change.]

The InitializeDynamic method performs primary terminal object creation for the pluggable terminal.

HRESULT InitializeDynamic(
  IID iidTerminalClass,
  DWORD dwMediaType,
  TERMINAL_DIRECTION Direction,
  MSP_HANDLE htAddress
);

Parameters

iidTerminalClass
[in] The IID_ for the class of the terminal being initialized.
dwMediaType
[in] ORed list of the media types supported by the terminal.
Direction
[in] The TERMINAL_DIRECTION descriptor for the terminal.
htAddress
[in] MSP handle for the address to associate with the terminal being created.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalInitialization


ITPluggableTerminalSuperclassInfo

[This is preliminary documentation and subject to change.]

The ITPluggableTerminalSuperclassInfo interface exposes methods that get the name and CLSID of a pluggable terminal class.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPluggableTerminalSuperclassInfo methods | Description
get_Name | Gets the terminal's friendly name.
get_CLSID | Gets the CLSID used to CoCreateInstance the terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITPluggableTerminalSuperclassInfo::get_CLSID

[This is preliminary documentation and subject to change.]

The get_CLSID method gets the CLSID used to CoCreateInstance the terminal.

HRESULT get_CLSID(
  BSTR * pCLSID
);

Parameters

pCLSID
[retval][out] The BSTR representation of the CLSID. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassInfo


ITPluggableTerminalSuperclassInfo::get_Name

[This is preliminary documentation and subject to change.]

The get_Name method gets the terminal's friendly name.

HRESULT get_Name(
  BSTR * pName
);

Parameters

pName
[retval][out] The BSTR representation of the friendly name. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassInfo


ITPluggableTerminalSuperclassRegistration

[This is preliminary documentation and subject to change.]

The ITPluggableTerminalSuperclassRegistration interface exposes methods that get and set information about a terminal superclass (name and CLSID). The interface also includes methods that list all pluggable terminal public CLSIDs (terminal classes) registered below this terminal class.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITPluggableTerminalSuperclassRegistration methods | Description
get_Name | Gets the friendly name for the terminal superclass.
put_Name | Sets the friendly name for the terminal superclass.
get_CLSID | Gets the CLSID used to CoCreateInstance the terminal.
put_CLSID | Sets the CLSID used to CoCreateInstance the terminal.
Add | Adds a pluggable terminal superclass.
Delete | Deletes a terminal superclass.
GetTerminalSuperclassInfo | Gets terminal superclass information.
get_TerminalClasses | Gets the terminal classes for the terminal superclass.
EnumerateTerminalClasses | Enumerates the terminal classes for the terminal superclass.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.


ITPluggableTerminalSuperclassRegistration::Add

[This is preliminary documentation and subject to change.]

The Add method adds a pluggable terminal superclass to the registry. If the superclass already exists, the method modifies the information for the superclass.

HRESULT Add( );

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Method failed.

Remarks

The Add method adds a new terminal superclass if the CLSID does not exist as an entry in the registry. The method modifies the information about a terminal superclass if the CLSID already exists in the registry.

If the CLSID for the terminal superclass was not set for terminal superclass, the Add method fails.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration, Delete


ITPluggableTerminalSuperclassRegistration::Delete

[This is preliminary documentation and subject to change.]

The Delete method removes the current terminal superclass from the registry.

HRESULT Delete( );

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Method failed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration, Add


ITPluggableTerminalSuperclassRegistration::EnumerateTerminalClasses

[This is preliminary documentation and subject to change.]

The EnumerateTerminalClasses method lists all terminal classes for the current terminal superclass.

HRESULT EnumerateTerminalClasses(
  IEnumTerminalClass ** ppTerminals
);

Parameters

ppTerminals
[out,retval] Pointer to the IEnumTerminalClass interface that enumerates the terminal classes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppTerminals parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration


ITPluggableTerminalSuperclassRegistration::GetTerminalSuperclassInfo

[This is preliminary documentation and subject to change.]

The GetTerminalSuperclassInfo method gets class information from the registry for the current terminal superclass.

HRESULT GetTerminalSuperclassInfo( );

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Method failed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration


ITPluggableTerminalSuperclassRegistration::get_CLSID

[This is preliminary documentation and subject to change.]

The get_CLSID method gets the CLSID used to CoCreateInstance the terminal.

HRESULT get_CLSID(
  BSTR * pCLSID
);

Parameters

pCLSID
[retval][out] The BSTR representation of the CLSID. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pCLSID parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration, put_CLSID


ITPluggableTerminalSuperclassRegistration::get_Name

[This is preliminary documentation and subject to change.]

The get_Name method gets the friendly name for the terminal superclass.

HRESULT get_Name(
  BSTR * pName
);

Parameters

pName
[retval][out] Pointer to a BSTR representation of the friendly name. The BSTR is allocated using SysAllocString. The BSTR argument should be deallocated by the client.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pName parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration, put_Name


ITPluggableTerminalSuperclassRegistration::get_TerminalClasses

[This is preliminary documentation and subject to change.]

The get_TerminalClasses method gets the terminal classes for this pluggable terminal superclass.

HRESULT get_TerminalClasses(
  VARIANT * pTerminals
);

Parameters

pTerminals
[retval][out] Pointer to a VARIANT containing an ITCollection of ITTerminal interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pTerminals parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration


ITPluggableTerminalSuperclassRegistration::put_CLSID

[This is preliminary documentation and subject to change.]

The put_CLSID method sets the CLSID used to CoCreateInstance the terminal.

HRESULT put_CLSID(
  BSTR bstrCLSID
);

Parameters

bstrCLSID
[in] The BSTR representation of the CLSID.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The bstrCLSID parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration, get_CLSID


ITPluggableTerminalSuperclassRegistration::put_Name

[This is preliminary documentation and subject to change.]

The put_Name method sets the friendly name for the terminal superclass.

HRESULT put_Name(
  BSTR bstrName
);

Parameters

bstrName
[in] The BSTR representation of the friendly name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The bstrName parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITPluggableTerminalSuperclassRegistration, get_Name


ITQOSEvent

The ITQOSEvent interface contains methods that retrieve the description of quality of service (QOS) events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_QOSEVENT, the method's pEvent parameter is an IDispatch pointer for the ITQOSEvent interface. The methods of this interface can be used to retrieve information concerning a QOS event that has occurred.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_QOSEVENT to enable reception of QOS events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITQOSEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface.
get_Event | Gets the QOS_EVENT descriptor of the event.
get_MediaType | Gets the media type description.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITCallInfo, QOS_EVENT, media type, Register Events code snippet


ITQOSEvent::get_Call

The get_Call method gets a pointer to the ITCallInfo interface for the call on which the QOS event occurred.

HRESULT get_Call(
  ITCallInfo **ppCall
);

Parameters

ppCall
[out, retval] Points to ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCall parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQOSEvent


ITQOSEvent::get_Event

The get_Event method gets the QOS_EVENT indicator.

HRESULT get_Event(
  QOS_EVENT *pQosEvent
);

Parameters

pQosEvent
[out, retval] Indicator of the QOS event type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pQosEvent parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQOSEvent, QOS_EVENT


ITQOSEvent::get_MediaType

The get_MediaType method gets the media type indicator.

HRESULT get_MediaType(
  long *plMediaType
);

Parameters

plMediaType
[out, retval] Indicates the media type for the call on which the QOS event occurred.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plMediaType parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQOSEvent, media type


ITRequest

The ITRequest interface allows an application to use Assisted Telephony. Assisted Telephony provides telephony-enabled applications with a simple mechanism for making phone calls without requiring the developer to become fully literate in telephony.

The Request object must be created using COM CoCreateInstance.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITRequest methods | Description
MakeCall | Makes call to designated party.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITRequest::MakeCall

The MakeCall method makes a call to the designated party.

HRESULT MakeCall(
  BSTR pDestAddress,
  BSTR pAppName,
  BSTR pCalledParty,
  BSTR pComment
);

Parameters

pDestAddress
[in] Pointer to a BSTR containing the destination address for the call.
pAppName
[in] Pointer to a BSTR containing the name of the application.
pCalledParty
[in] Pointer to a BSTR containing the called party name.
pComment
[in] Pointer to a BSTR containing a comment.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPIERR_NOREQUESTRECIPIENT | No application exists that can handle the assisted telephony request.
TAPIERR_INVALDESTADDRESS | The destination address is not valid.
TAPIERR_REQUESTQUEUEFULL | The TAPI Server request queue is full and cannot handle another assisted telephony request.

Remarks

The application must use SysAllocString to allocate memory for the pDestAddress, pAppName, pCalledParty, and pComment parameters. The application must use SysFreeString to free the memory when the variables are no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITRequest


ITRequestEvent

The ITRequestEvent interface contains methods that allow an application to receive and process Assisted Telephony request events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_REQUEST, the method's pEvent parameter is an IDispatch pointer for the ITRequestEvent interface. The methods of this interface can be used to retrieve information concerning a request event that has occurred.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_REQUEST event to enable reception of request events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITRequestEvent methods | Description
get_RegistrationInstance | Gets the registration instance.
get_RequestMode | Gets the request mode descriptor.
get_DestAddress | Gets the destination address.
get_AppName | Gets the name of the application.
get_CalledParty | Gets the called party.
get_Comment | Gets a comment associated with the request event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITRequest, Register Events code snippet


ITRequestEvent::get_AppName

The get_AppName method gets the name of the application.

HRESULT get_AppName(
  BSTR *ppAppName
);

Parameters

ppAppName
[out, retval] Pointer to a BSTR containing the application name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppAppName is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppAppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITRequestEvent


ITRequestEvent::get_CalledParty

The get_CalledParty method gets the called party.

HRESULT get_CalledParty(
  BSTR *ppCalledParty
);

Parameters

ppCalledParty
[out, retval] Pointer to a BSTR containing the called party identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCalledParty is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppCalledParty parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITRequestEvent


ITRequestEvent::get_Comment

The get_Comment method gets the comment.

HRESULT get_Comment(
  BSTR *ppComment
);

Parameters

ppComment
[out, retval] Pointer to a BSTR containing the comment.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppComment is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppComment parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITRequestEvent


ITRequestEvent::get_DestAddress

The get_DestAddress method gets the destination address.

HRESULT get_DestAddress(
  BSTR *ppDestAddress
);

Parameters

ppDestAddress
[out, retval] Pointer to a BSTR containing the destination address.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppDestAddress is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppDestAddress parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITRequestEvent


ITRequestEvent::get_RegistrationInstance

The get_RegistrationInstance method gets the registration instance.

HRESULT get_RegistrationInstance(
  long *plRegistrationInstance
);

Parameters

plRegistrationInstance
[out, retval] Pointer to the registration instance.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plRegistrationInstance is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITRequestEvent


ITRequestEvent::get_RequestMode

The get_RequestMode method gets the mode of the request.

HRESULT get_RequestMode(
  long *plRequestMode
);

Parameters

plRequestMode
[out, retval] Pointer to the request mode.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plRequestMode is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITRequestEvent


ITScriptableAudioFormat

[This is preliminary documentation and subject to change.]

The ITScriptableAudioFormat interface is used by scriptable clients to get the audio format from, or set the audio format for, the track. The interface provides properties for each member from the WAVEFORMATEX structure.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITScriptableAudioFormat methods | Description
get_Channels | Gets the value for the nChannels member in the WAVEFORMATEX structure.
put_Channels | Sets the value for the nChannels member in the WAVEFORMATEX structure.
get_SamplesPerSec | Gets the value for the nSamplesPerSec member in the WAVEFORMATEX structure.
put_SamplesPerSec | Sets the value of the nSamplesPerSec member in the WAVEFORMATEX structure.
get_AvgBytesPerSec | Gets the value for the nAvgBytesPerSec member in the WAVEFORMATEX structure.
put_AvgBytesPerSec | Sets the value for the nAvgBytesPerSec member in the WAVEFORMATEX structure.
get_BlockAlign | Gets the value for the nBlockAlign member in the WAVEFORMATEX structure.
put_BlockAlign | Sets the value for the nBlockAlign member in the WAVEFORMATEX structure.
get_BitsPerSample | Gets the value for the wBitsPerSample member in the WAVEFORMATEX structure.
put_BitsPerSample | Sets the value for the wBitsPerSample member in the WAVEFORMATEX structure.
get_FormatTag | Gets the value for the wFormatTag member in the WAVEFORMATEX structure.
put_FormatTag | Sets the value for the wFormatTag member in the WAVEFORMATEX structure.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITScriptableAudioFormat::get_AvgBytesPerSec

[This is preliminary documentation and subject to change.]

The get_AvgBytesPerSec method returns the value for the nAvgBytesPerSec member in the WAVEFORMATEX structure.

HRESULT get_AvgBytesPerSec(
  long * pVal
);

Parameters

pVal
[out,retval] Pointer to the value for the nAvgBytesPerSec member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded
E_POINTER | The pVal argument is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, put_AvgBytesPerSec


ITScriptableAudioFormat::get_BitsPerSample

[This is preliminary documentation and subject to change.]

The get_BitsPerSample method returns the value for the wBitsPerSample member in the WAVEFORMATEX structure.

HRESULT get_BitsPerSample(
  long * pVal
);

Parameters

pVal
[out,retval] Pointer to the value of the wBitsPerSample member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal argument is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, put_BitsPerSample


ITScriptableAudioFormat::get_BlockAlign

[This is preliminary documentation and subject to change.]

The get_BlockAlign method returns the value for the nBlockAlign member in the WAVEFORMATEX structure.

HRESULT get_BlockAlign(
  long * pVal
);

Parameters

pVal
[out,retval] Pointer to the value of the nBlockAlign member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal argument is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, put_BlockAlign


ITScriptableAudioFormat::get_Channels

[This is preliminary documentation and subject to change.]

The get_Channels method returns the value for the nChannels member in the WAVEFORMATEX structure.

HRESULT get_Channels(
  long * pVal
);

Parameters

pVal
[out,retval] Pointer to the value of the nChannels member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal argument is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, put_Channels


ITScriptableAudioFormat::get_FormatTag

[This is preliminary documentation and subject to change.]

The get_FormatTag method returns the value for the wFormatTag member in the WAVEFORMATEX structure.

HRESULT get_FormatTag(
  long * pVal
);

Parameters

pVal
[out,retval] Pointer to the value of the wFormatTag member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal argument is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, put_FormatTag


ITScriptableAudioFormat::get_SamplesPerSec

[This is preliminary documentation and subject to change.]

The get_SamplesPerSec method returns the value for the nSamplesPerSec member in the WAVEFORMATEX structure.

HRESULT get_SamplesPerSec(
  long * pVal
);

Parameters

pVal
[out,retval] Pointer to the value of the nSamplesPerSec member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal argument is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, put_SamplesPerSec


ITScriptableAudioFormat::put_AvgBytesPerSec

[This is preliminary documentation and subject to change.]

The put_AvgBytesPerSec method sets the nAvgBytesPerSec member in the WAVEFORMATEX structure.

HRESULT put_AvgBytesPerSec(
  const long nNewVal
);

Parameters

nNewVal
[in] New value for the nAvgBytesPerSec member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, get_AvgBytesPerSec


ITScriptableAudioFormat::put_BitsPerSample

[This is preliminary documentation and subject to change.]

The put_BitsPerSample method sets the wBitsPerSample member in the WAVEFORMATEX structure.

HRESULT put_BitsPerSample(
  const long nNewVal
);

Parameters

nNewVal
[in] New value for the wBitsPerSample member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, get_BitsPerSample


ITScriptableAudioFormat::put_BlockAlign

[This is preliminary documentation and subject to change.]

The put_BlockAlign method sets the nBlockAlign member in the WAVEFORMATEX structure.

HRESULT put_BlockAlign(
  const long nNewVal
);

Parameters

nNewVal
[in] New value for the nBlockAlign member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, get_BlockAlign


ITScriptableAudioFormat::put_Channels

[This is preliminary documentation and subject to change.]

The put_Channels method sets the nChannels member in the WAVEFORMATEX structure.

HRESULT put_Channels(
  const long nNewVal
);

Parameters

nNewVal
[in] New value for the nChannels member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, get_Channels


ITScriptableAudioFormat::put_FormatTag

[This is preliminary documentation and subject to change.]

The put_FormatTag method sets the wFormatTag member in the WAVEFORMATEX structure.

HRESULT put_FormatTag(
  const long nNewVal
);

Parameters

nNewVal
[in] New value for the wFormatTag member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, get_FormatTag


ITScriptableAudioFormat::put_SamplesPerSec

[This is preliminary documentation and subject to change.]

The put_SamplesPerSec method sets the nSamplesPerSec member in the WAVEFORMATEX structure.

HRESULT put_SamplesPerSec(
  const long nNewVal
);

Parameters

nNewVal
[in] New value for the nSamplesPerSec member in the WAVEFORMATEX structure.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITScriptableAudioFormat, get_SamplesPerSec


ITStaticAudioTerminal

[This is preliminary documentation and subject to change.]

The ITStaticAudioTerminal interface is an interface that TAPI 3.1 MSPs must expose on all static audio terminals. The interface defines methods on static audio terminal objects that are needed to support phone devices.

If an MSP's audio terminals are for devices that are not accessible via standard audio APIs, then a QueryInterface on ITTerminal(IID_ITStaticAudioTerminal) should return E_NOINTERFACE, and it will be impossible to associate a USB phone with any of these audio terminals in TAPI 3.1.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITStaticAudioTerminal methods | Description
get_WaveId | Gets the wave ID for the audio device used to implement this terminal.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITStaticAudioTerminal::get_WaveId

[This is preliminary documentation and subject to change.]

The get_WaveId method returns the wave ID for the audio device used to implement this terminal.

HRESULT get_WaveId(
  long * plWaveId
);

Parameters

plWaveId
[out,retval] Pointer to space for a long where, on success, the method will store the wave ID for this terminal.

Remarks

All MSPs must implement the get_WaveId method on their audio terminals for TAPI's association of phone devices and audio terminals to work for calls on that MSP's addresses. See ITStaticAudioTerminal for what to do for audio terminals that are not accessible via standard Windows audio APIs.

All other terminals must return the correct wave ID, even if the internal implementation of the terminal does not use wave. In such cases, a mapping should be possible between the identifier used in the nonwave APIs and the wave ID. The MSP must perform this mapping.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITStaticAudioTerminal


ITStream (MSPI)

The ITStream interface is available if an MSP is associated with the call. The methods of this interface allow an application to retrieve information on a stream; to start, pause, or stop the stream; and to select or unselect terminals on a stream.

The ITStream interface is implemented by an MSP. Please see ITStream in the MSP Interface section for details on this interface.


ITStreamControl (MSPI)

The ITStreamControl interface is exposed on the Call Object if there is an associated MSP. The methods of this interface allow an application to create and remove streams.

The ITStreamControl interface is implemented by an MSP. Please see ITStreamControl in the MSP Interface section for details on this interface.


ITSubStream (MSPI)

The ITSubStream interface is available if an MSP is associated with the call and it implements substreams. The methods of this interface allow an application to retrieve information on a substream; to start, pause, or stop the substream; and to select or unselect terminals on a substream.

The ITSubStream interface is implemented by an MSP. Please see ITSubStream in the MSP Interface section for details on this interface.


ITSubStreamControl (MSPI)

The ITSubStreamControl interface is exposed on the Stream Object if there is an associated MSP and it implements substreams. The methods of this interface allow an application to create and remove substreams.

The ITSubStreamControl interface is implemented by an MSP. Please see ITSubStreamControl in the MSP Interface section for details on this interface.


ITTAPI

The ITTAPI interface is the base interface for the TAPI object. The TAPI object is created by CoCreateInstance. For information on CoCreateInstance, see documentation on COM. All other TAPI 3.0 objects are created by TAPI 3.0 itself.

ITTAPI methods are provided to initialize a TAPI session, enumerate available addresses, register for CallHub and CallEvent notifications, and shut down a TAPI session.

The ITTAPI2 interface derives from the ITTAPI interface. It adds additional methods on the TAPI object to support phone devices.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTAPI methods | Description
Initialize | Initializes TAPI object.
Shutdown | Shuts down TAPI.
get_Addresses | Creates a collection of addresses currently available. Provided for Automation client applications, such as those written in Microsoft Visual Basic.
EnumerateAddresses | Enumerates addresses currently available.
RegisterCallNotifications | Registers for call notification events.
UnregisterNotifications | Removes notifications for TAPI object.
get_CallHubs | Creates a collection of currently available call hubs. Provided for Automation client applications, such as those written in Visual Basic.
EnumerateCallHubs | Enumerates currently available call hubs.
SetCallHubTracking | Enables or disables CallHub tracking.
EnumeratePrivateTAPIObjects | Not implemented.
get_PrivateTAPIObjects | Not implemented.
RegisterRequestRecipient | Registers an application to handle assisted telephony requests.
SetAssistedTelephonyPriority | Sets application priority to handle assisted telephony requests.
SetApplicationPriority | Sets priority under which applications will have calls passed to them by media.
put_EventFilter | Sets the event filter mask. If no filter is set, no events are received.
get_EventFilter | Get the current event filter mask.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

TAPI Object, ITTAPI2


ITTAPI::EnumerateAddresses

The EnumerateAddresses method enumerates the addresses that are currently available. Provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Addresses method.

HRESULT EnumerateAddresses(
  IEnumAddress **ppEnumAddress
);

Parameters

ppEnumAddress
[out, retval] Pointer to the IEnumAddress interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumAddress parameter is not a valid pointer.
E_INVALIDARG | The TAPI object has not been initialized.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

An application typically uses this enumeration to check the capabilities of each address and determine which are useful for current purposes.

If an expected address is not found, this may indicate that the appropriate service provider has not been installed or is not working correctly.

The application must call the Release method on the returned enumeration to free resources associated with it.

If an address is created or removed during a TAPI session, the application will be notified through the ITTAPIEventNotification interface. If an address has been created, such as by installing a Plug and Play device, the ITTAPIEventNotification::Event returns the TE_ADDRESSCREATE member of the TAPIOBJECT_EVENT enum. If an address is removed, ITTAPIEventNotification::Event returns TE_ADDRESSREMOVE. Calling EnumerateAddresses after these events will reflect the current addresses.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, get_Addresses, IEnumAddress, ITAddress, TAPI Object, Register Events code snippet


ITTAPI::EnumerateCallHubs

The EnumerateCallHubs method enumerates the currently available call hubs. Provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Callhubs method.

HRESULT EnumerateCallHubs(
  IEnumCallHub **ppEnumCallHub
);

Parameters

ppEnumCallHub
[out, retval] Pointer to the IEnumCallHub interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumCallHub parameter is not a valid pointer.
E_INVALIDARG | The TAPI object has not been initialized.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, TAPI Object


ITTAPI::get_Addresses

The get_Addresses method creates a collection of addresses that are currently available. Provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateAddresses method.

HRESULT get_Addresses(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to a VARIANT containing an ITCollection of ITAddress interface pointers (address objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pVariant parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, EnumerateAddresses, IEnumAddress, ITAddress, TAPI Object, ITCollection


ITTAPI::get_CallHubs

The get_CallHubs method creates a collection of the currently available call hubs. Provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateCallHubs method.

HRESULT get_CallHubs(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITCallHub interface pointers (CallHub objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pVariant parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, TAPI Object, ITCollection, ITCallHub


ITTAPI::get_EventFilter

The get_EventFilter method gets the current event filter mask. The mask is a series of ORed members of the TAPI_EVENT enumeration.

HRESULT get_EventFilter(
  long * plFilterMask
);

Parameters

plFilterMask
[out] Pointer to the event filter mask.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, put_EventFilter, TAPI_EVENT, ITTAPIEventNotification, Events overview, Register Events code snippet


ITTAPI::Initialize

The Initialize method initializes TAPI. This method must be called before calling any other TAPI 3.0 method. The application must call the Shutdown method when ending a TAPI session.

HRESULT Initialize();

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
S_FALSE | TAPI has already been initialized.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, TAPI Object


ITTAPI::put_EventFilter

The put_EventFilter method sets the event filter mask. The mask is a series of ORed members of the TAPI_EVENT enumeration.

Note You must call this method to enable reception of events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events.

HRESULT put_EventFilter(
  long lFilterMask
);

Parameters

lFilterMask
[in] Event filter mask.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, get_EventFilter, TAPI_EVENT, ITTAPIEventNotification, Events overview, Register Events code snippet


ITTAPI::RegisterCallNotifications

The RegisterCallNotifications method sets which new call notifications an application will receive. The application must call the method for each address, indicating media type or types it can handle, and specifying the privileges it requests.

An application that will make only outgoing calls does not need to call this method.

The ITTAPIEventNotification outgoing interface must be registered prior to calling this method.

If both owner and monitor privileges are needed for an address, this method should be called only once, with both fMonitor and fOwner set to TRUE.

HRESULT RegisterCallNotifications(
  ITAddress *pAddress,
  VARIANT_BOOL fMonitor,
  VARIANT_BOOL fOwner,
  long lMediaTypes,
  long lCallbackInstance,
  long *plRegister
);

Parameters

pAddress
[in] Pointer to ITAddress interface.
fMonitor
[in] Boolean value indicating whether the application will monitor calls. VARIANT_TRUE indicates that the application will monitor calls; VARIANT_FALSE that it will not.
fOwner
[in] Boolean value indicating whether the application will own incoming calls. VARIANT_TRUE indicates that the application will own incoming calls; VARIANT_FALSE indicates that it will not.
lMediaTypes
[in] Media types that can be handled by the application.
lCallbackInstance
[in] Callback instance to be used by the TAPI 3.0 DLL. Can be the gulAdvise value returned by IConnectionPoint::Advise during registration of the ITTAPIEventNotification outgoing interface.
plRegister
[out, retval] On success, the returned value that is used by ITTAPI::UnregisterNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plRegister parameter is not a valid pointer.
TAPI_E_NOT_INITIALIZED | The TAPI object has not been initialized.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

If multiple calls of this method are used on one address, the information about participant calls from a call hub may be confusing if a call that is already being monitored by the application is handed off to it.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, ITTAPIEventNotification, ITCallNotificationEvent, TAPI Object, Events overview, Register Events code snippet


ITTAPI::RegisterRequestRecipient

The RegisterRequestRecipient method registers an application instance as being the proper one to handle assisted telephony requests.

HRESULT RegisterRequestRecipient(
  long lRegistrationInstance,
  long lRequestMode,
  VARIANT_BOOL fEnable
);

Parameters

lRegistrationInstance
[in] Pointer to registration instance.
lRequestMode
[in] Request mode.
fEnable
[in] VARIANT_TRUE indicates that the caller wants to register as the handler; VARIANT_FALSE that it wants to unregister as the handler.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The TAPI object has not been initialized.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, ITRequest, MakeCall, ITRequestEvent, TAPI Object


ITTAPI::SetApplicationPriority

The SetApplicationPriority method allows an application to set its priority in the handoff priority list for a particular media type or Assisted Telephony request mode, or to remove itself from the priority list.

HRESULT SetApplicationPriority(
  BSTR pAppFilename,
  long lMediaType,
  VARIANT_BOOL fPriority
);

Parameters

pAppFilename
[in] Pointer to BSTR containing name of application.
lMediaType
[in] Media associated with application.
fPriority
[in] The new priority for the application. If the value VARIANT_FALSE is passed, the application is removed from the priority list for the specified media or request mode (if it was already not present, no error is generated). If the value VARIANT_TRUE is passed, the application is inserted as the highest-priority application for the media or request mode (and removed from a lower-priority position, if it was already in the list).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysAllocString to allocate memory for the pAppFilename parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, ITBasicCallControl::HandoffIndirect, TAPI Object


ITTAPI::SetAssistedTelephonyPriority

The SetAssistedTelephonyPriority method sets the application priority to handle assisted telephony requests.

HRESULT SetAssistedTelephonyPriority(
  BSTR pAppFilename,
  VARIANT_BOOL fPriority
);

Parameters

pAppFilename
[in] Pointer to a BSTR containing the name of the application.
fPriority
[in] Set to VARIANT_FALSE to disable, VARIANT_TRUE to enable.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysAllocString to allocate memory for the pAppFilename parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, ITBasicCallControl::HandoffIndirect, TAPI Object


ITTAPI::SetCallHubTracking

The SetCallHubTracking method enables or disables CallHub tracking.

HRESULT SetCallHubTracking(
  VARIANT pAddresses,
  VARIANT_BOOL bTracking
);

Parameters

pAddresses
[in] Pointer to a VARIANT containing an ITCollection of ITAddress interface pointers.
bTracking
[in] VARIANT_TRUE to enable tracking, VARIANT_FALSE to disable.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The TAPI object has not been initialized.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, TAPI Object


ITTAPI::Shutdown

The Shutdown method shuts down a TAPI session.

HRESULT Shutdown();

Parameters

None.

Return Values

Value | Meaning
S_OK | Method succeeded.
S_FALSE | TAPI session has already been shut down.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

One reason why Shutdown might fail is if Initialize was not previously called successfully.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, TAPI Object


ITTAPI::UnregisterNotifications

The UnregisterNotifications method removes any incoming call notification registrations that have been performed using ITTAPI::RegisterCallNotifications.

HRESULT UnregisterNotifications(
  long lRegister
);

Parameters

lRegister
[in] The value returned by the RegisterCallNotifications method in the plRegister parameter.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The TAPI object has not yet been initialized or the lRegister parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI, RegisterCallNotifications, TAPI Object


ITTAPI2

[This is preliminary documentation and subject to change.]

The ITTAPI2 interface derives from the ITTAPI interface. It adds additional methods on the TAPI object to support phone devices.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTAPI2 methods | Description
get_Phones | Gets the collection of phone objects that are available.
EnumeratePhones | Enumerates the phone objects that are available.
CreateEmptyCollectionObject | Creates an empty collection object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI


ITTAPI2::CreateEmptyCollectionObject

[This is preliminary documentation and subject to change.]

The CreateEmptyCollectionObject method creates an empty collection object. The collection can be filled with ITDetectTone or ITCustomTone objects for use with the DetectTonesByCollection method or the GenerateCustomTonesByCollection method, respectively.

This method is intended for Visual Basic and scripting applications.

HRESULT CreateEmptyCollectionObject(
  ITCollection2 ** ppCollection
);

Parameters

ppCollection
[out,retval] Pointer to an ITCollection2 interface on the new collection object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCollection parameter is not a valid pointer.
E_OUTOFMEMORY | There is not enough memory to allocate the object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI2, ITCollection2, ITDetectTone, ITCustomTone


ITTAPI2::EnumeratePhones

[This is preliminary documentation and subject to change.]

The EnumeratePhones method enumerates the phone objects corresponding to the phone devices. If there are no phones available that can be used with the address, this method produces an empty enumeration and returns S_OK.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_Phones method.

HRESULT EnumeratePhones(
  IEnumPhone ** ppEnumPhone
);

Parameters

ppEnumPhone
[out,retval] Pointer to an IEnumPhone interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI2, IEnumPhone


ITTAPI2::get_Phones

[This is preliminary documentation and subject to change.]

The get_Phones method enumerates the phone objects corresponding to the phone devices. If there are no phones available that can be used with the address, this method produces an empty collection and returns S_OK.

This method is intended for Visual Basic and scripting applications. C/C++ applications will find the EnumeratePhones method more convenient.

HRESULT get_Phones(
  VARIANT * pPhones
);

Parameters

pPhones
[out,retval] Pointer to a VARIANT containing an ITCollection of IEnumPhone interface pointers.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPI2, IEnumPhone, IEnumPhone


ITTAPICallCenter

The ITTAPICallCenter interface provides an entry point into call center controls. It exposes methods that allow an application to discover available agent handlers. The agent handler interface can then be used to access the other elements of a call center, such as ACD groups, agents, and queues.

Please see About TAPI 3.0 Call Center Controls for additional information.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTAPICallCenter methods | Description
EnumerateAgentHandlers | Enumerates ITAgentHandler interfaces currently associated with the call center.
get_AgentHandlers | Creates a collection of ITAgentHandler interfaces currently associated with the call center. Provided for Automation client applications, such as those written in Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

About TAPI 3.0 Call Center Controls, Call Center Interfaces, TAPI Object


ITTAPICallCenter::EnumerateAgentHandlers

The EnumerateAgentHandlers method enumerates agent handlers that are currently associated with the call center. Provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_AgentHandlers method.

HRESULT EnumerateAgentHandlers(
  IEnumAgentHandler **ppEnumHandler
);

Parameters

ppEnumHandler
[out, retval] Pointer to IEnumAgentHandler enumerator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumHandler parameter is not a valid pointer.
E_INVALIDARG | The TAPI object has not been initialized.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPICallCenter, IEnumAgentHandler, TAPI Object


ITTAPICallCenter::get_AgentHandlers

The get_AgentHandlers method creates a collection of agent handlers that are currently associated with the call center. Provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateAgentHandlers method.

HRESULT get_AgentHandlers(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to a VARIANT containing an ITCollection of ITAgentHandler interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pVariant parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPICallCenter, IEnumAgentHandler, TAPI Object, ITCollection, ITAgentHandler


ITTAPIEventNotification

The ITTAPIEventNotification interface is an outgoing interface that allows an application to control the processing of event information. The application must implement this interface: it must create a COM object that supports this interface, and then register it using the COM standard IConnectionPointContainer and IConnectionPoint interfaces.

The ITTAPIEventNotification::Event method of this interface is called by TAPI in response to an event. Typically, the application implements a set of switch statements that use the value of a TAPI_EVENT enumerator to determine the response to the event.

After registration of this interface, the application calls ITTAPI::put_EventFilter to specify which events it must receive. If this method is not called, the application will not receive any events.

The application may then call ITTAPI::RegisterCallNotifications to notify TAPI of addresses and media types for which the application will accept incoming call sessions.

Please refer to the Event overview for additional information on event handling.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTAPIEventNotification methods | Description
Event | Gets TAPI_EVENT descriptor for an asynchronous event notification.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

TAPI_EVENT, TAPI Object, Event overview, Register Events code snippet, ITACDGroupEvent, ITAddressEvent, ITAgentEvent, ITAgentHandlerEvent, ITAgentSessionEvent, ITCallHubEvent, ITCallInfoChangeEvent, ITCallMediaEvent, ITCallNotificationEvent, ITCallStateEvent, ITDigitDetectionEvent, ITDigitGenerationEvent, ITParticipantEvent, ITQOSEvent, ITQueueEvent, ITRequestEvent, ITTAPIObjectEvent


ITTAPIEventNotification::Event

The Event method is called by TAPI to determine the response to an asynchronous event notification. The application implements a set of case statements that use TapiEvent to determine the type of event being signaled, then calls IUnknown::QueryInterface on pEvent to obtain the appropriate event interface pointer. Each event defined by TAPI 3.0 has an interface associated with it. The specific events handled depend on the needs of the application.

HRESULT Event(
  TAPI_EVENT TapiEvent,
  IDispatch *pEvent
);

Parameters

TapiEvent
[in] TAPI_EVENT indicator of the event.
pEvent
[in] Pointer to an IDispatch interface of the object associated with this event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pEvent parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

You must call the ITTAPI::put_EventFilter method to set the event filter mask and enable reception of events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification, TAPI_EVENT, Events overview, Register Events code snippet


ITTAPIObjectEvent

The ITTAPIObjectEvent interface contains methods that retrieve the description of TAPI object events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_TAPIOBJECT, the method's pEvent parameter is an IDispatch pointer for the ITTAPIObjectEvent interface. The methods of this interface can be used to retrieve information concerning the TAPI object change that has occurred.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_TAPIOBJECT event to enable reception of TAPI object events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

The ITTAPIObjectEvent2 interface is an extension of the ITTAPIObjectEvent interface. ITTAPIObjectEvent2 exposes an additional method that returns a pointer to an ITPhone interface on the phone object that caused the TAPI object event.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTAPIObjectEvent methods | Description
get_TAPIObject | Gets a pointer to the ITTAPI object on which the event occurred.
get_Event | Gets the TAPI_EVENT descriptor of an asynchronous event notification.
get_Address | Gets a pointer to the ITAddress interface.
get_CallbackInstance | Get the callback instance associated with the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, TAPI Object, Register Events code snippet, ITTAPIObjectEvent2


ITTAPIObjectEvent::get_Address

The get_Address method gets a pointer to the Address object on which the event occurred.

HRESULT get_Address(
  ITAddress **ppAddress
);

Parameters

ppAddress
[out, retval] Pointer to an ITAddress interface pointer.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIObjectEvent, TAPI Object


ITTAPIObjectEvent::get_CallbackInstance

The get_CallbackInstance method gets a pointer to the callback instance associated with the event.

HRESULT get_CallbackInstance(
  long * plCallbackInstance
);

Parameters

plCallbackInstance
[out, retval] Pointer to the callback instance returned by ITTAPI::RegisterCallNotifications.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIObjectEvent, TAPI Object, ITTAPI::RegisterCallNotifications


ITTAPIObjectEvent::get_Event

The get_Event method gets information concerning an asynchronous event notification. The application uses TAPIOBJECT_EVENT to determine what type of event is being signaled.

HRESULT get_Event(
  TAPIOBJECT_EVENT *pEvent
);

Parameters

pEvent
[out, retval] TAPIOBJECT_EVENT indicator of the event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pEvent parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIObjectEvent, TAPIOBJECT_EVENT, TAPI Object


ITTAPIObjectEvent::get_TAPIObject

The get_TAPIObject method gets a pointer to the TAPI object on which the event occurred.

HRESULT get_TAPIObject(
  ITTAPI **ppTAPIObject
);

Parameters

ppTAPIObject
[out, retval] Pointer to an ITTAPI interface of the TAPI object on which the event occurred.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTAPIObject parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIObjectEvent, TAPI Object


ITTAPIObjectEvent2

[This is preliminary documentation and subject to change.]

The ITTAPIObjectEvent2 interface is an extension of the ITTAPIObjectEvent interface. ITTAPIObjectEvent2 exposes an additional method that returns a pointer to an ITPhone interface on the phone object that caused the TAPI object event.

When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_TAPIOBJECT, the method's pEvent parameter is an IDispatch pointer for the ITTAPIObjectEvent2 interface.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_TAPIOBJECT event to enable reception of TAPI object events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTAPIObjectEvent2 methods | Description
get_Phone | Returns a pointer to the ITPhone interface on the phone object that caused this notification of a TAPI object event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIObjectEvent


ITTAPIObjectEvent2::get_Phone

[This is preliminary documentation and subject to change.]

The get_Phone method returns a pointer to the ITPhone interface on the phone object that caused this TAPI object event to be fired.

HRESULT get_Phone(
  ITPhone ** ppPhone
);

Parameters

ppPhone
[out,retval] Pointer to the ITPhone interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIObjectEvent2, ITPhone


ITTerminal (MSPI)

The ITTerminal interface is the base interface for a Terminal object. It provides methods for obtaining information such as the terminal class and the media supported.

The ITTerminal interface is implemented by an MSP and is not available if there is no media service provider associated with the address. Please see ITTerminal in the MSP Interface section for details on this interface.


ITTerminalEvent (MSPI)

When the ITTAPIEventNotification::Event method returns TAPI_EVENT equal to TE_TERMINAL, the methods exposed by the ITTerminalEvent interface can be used to retrieve information concerning the terminal event that has occurred, if an MSP exists.

The ITTerminalEvent interface is implemented by an MSP and is not available if there is no media service provider associated with the address. Please see ITTerminalEvent in the MSP Interface section for details on this interface.


ITTerminalSupport (MSPI)

The ITTerminalSupport interface is exposed on an Address object if an MSP exists. The methods of this interface allow an application to discover available terminals and/or create one, and get pointers to required Terminal objects.

The ITTerminalSupport interface is implemented by an MSP and is not available if there is no media service provider associated with the address. Please see ITTerminalSupport in the MSP Interface section for details on this interface.


ITToneDetectionEvent

[This is preliminary documentation and subject to change.]

The ITToneDetectionEvent interface exposes methods that allow an application to retrieve information about a tone detection event.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITToneDetectionEvent methods | Description
get_Call | Gets a pointer to the ITCallInfo interface for the call on which the event occurred.
get_AppSpecific | Gets the application-defined tag that identifies the tone.
get_ToneListID | Gets the tone list ID for the tone that was detected.
get_TickCount | Gets the "tick count" (number of milliseconds since Windows started) at which the tone was detected.
get_CallbackInstance | Gets a pointer to the application's callback function that will process the event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.


ITToneDetectionEvent::get_AppSpecific

[This is preliminary documentation and subject to change.]

The get_AppSpecific method gets the application-defined tag that identifies the tone associated with the tone detection event.

HRESULT get_AppSpecific(
  long * plAppSpecific
);

Parameters

plAppSpecific
[out,retval] Pointer to a value to receive the application-specific identifier for the tone, as defined in the ITDetectTone object or in the LINEMONITORTONE structure.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plAppSpecific parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITToneDetectionEvent, LINEMONITORTONE


ITToneDetectionEvent::get_Call

[This is preliminary documentation and subject to change.]

The get_Call method gets a pointer to the call information interface for the call object on which the tone detection event occurred.

HRESULT get_Call(
  ITCallInfo ** ppCallInfo
);

Parameters

ppCallInfo
[out,retval] Pointer to the ITCallInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppCallInfo parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITToneDetectionEvent, ITCallInfo


ITToneDetectionEvent::get_CallbackInstance

[This is preliminary documentation and subject to change.]

The get_CallbackInstance method gets a pointer to the application's callback function that will process the event.

HRESULT get_CallbackInstance(
  long * plCallbackInstance
);

Parameters

plCallbackInstance
[out,retval] Pointer to the callback instance returned by the ITTAPI::RegisterCallNotifications method.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCallbackInstance parameter is not a valid pointer.
8 | LegacyMediaControl2 Enums

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITToneDetectionEvent, ITTAPI::RegisterCallNotifications


ITToneDetectionEvent::get_TickCount

[This is preliminary documentation and subject to change.]

The get_TickCount method gets the "tick count" (the number of milliseconds since Windows started) at which the tone was detected.

HRESULT get_TickCount(
  long * plTickCount
);

Parameters

plTickCount
[out,retval] Pointer to a value to receive the tick count.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plTickCount parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITToneDetectionEvent


ITToneDetectionEvent::get_ToneListID

[This is preliminary documentation and subject to change.]

The get_ToneListID method gets the tone list ID for the tone that was detected.

HRESULT get_ToneListID(
  long * plToneListID
);

Parameters

plToneListID
[out,retval] Pointer to a value to receive the index of the ITDetectTone object or the LINEMONITORTONE structure for the tone that generated the event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plToneListID parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3if.h.
Library: Use Uuid.lib.

See Also

ITToneDetectionEvent, ITDetectTone, LINEMONITORTONE


ITToneTerminalEvent

[This is preliminary documentation and subject to change.]

The ITToneTerminalEvent interface contains methods that retrieve the description of tone terminal events that have occurred.

When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_TONETERMINAL, the method's pEvent parameter is an IDispatch pointer for the ITToneTerminalEvent interface.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes TE_TONETERMINAL to enable reception of tone terminal events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITToneTerminalEvent methods | Description
get_Terminal | Gets the terminal on which the event occurred.
get_Call | Gets the call on which the event occurred.
get_Error | Gets the error code involved in the event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITToneTerminalEvent::get_Call

[This is preliminary documentation and subject to change.]

The get_Call method retrieves an interface pointer for the call object on which the event occurred.

HRESULT get_Call(
  ITCallInfo ** ppCall
);

Parameters

ppCall
[out,retval] Pointer to the ITCallInfo interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITToneTerminalEvent, ITCallInfo


ITToneTerminalEvent::get_Error

[This is preliminary documentation and subject to change.]

The get_Error method returns an HRESULT cast of the error code involved in the event.

HRESULT get_Error(
  HRESULT * phrErrorCode
);

Parameters

phrErrorCode
[out,retval] HRESULT cast of the error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITToneTerminalEvent


ITToneTerminalEvent::get_Terminal

[This is preliminary documentation and subject to change.]

The get_Terminal method returns an ITTerminal pointer for the tone terminal on which the event occurred.

HRESULT get_Terminal(
  ITTerminal ** ppTerminal
);

Parameters

ppTerminal
[out,retval] Pointer to the ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITToneTerminalEvent, ITTerminal


ITTTSTerminalEvent

[This is preliminary documentation and subject to change.]

The ITTTSTerminalEvent interface contains methods that retrieve the description of Text-to-Speech (TTS) terminal events that have occurred.

When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_TTSTERMINAL, the method's pEvent parameter is an IDispatch pointer for the ITTTSTerminalEvent interface.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes TE_TTSTERMINAL to enable reception of Text-to-Speech terminal events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTTSTerminalEvent methods | Description
get_Terminal | Gets the ITTerminal interface pointer for the terminal object involved in the terminal event.
get_Call | Gets the ITCallInfo interface pointer for the call object involved in the terminal event.
get_Error | Gets the error code involved in the terminal event.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITTTSTerminalEvent::get_Call

[This is preliminary documentation and subject to change.]

The get_Call method returns an ITCallInfo interface pointer for the call involved in the terminal event.

HRESULT get_Call(
  ITCallInfo ** ppCall
);

Parameters

ppCall
[out,retval] Pointer to the ITCallInfo interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTTSTerminalEvent, ITCallInfo


ITTTSTerminalEvent::get_Error

[This is preliminary documentation and subject to change.]

The get_Error method gets an HRESULT cast of the error code involved in the terminal event.

HRESULT get_Error(
  HRESULT * phrErrorCode
);

Parameters

phrErrorCode
[out,retval] Pointer to the HRESULT cast of the error code.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTTSTerminalEvent


ITTTSTerminalEvent::get_Terminal

[This is preliminary documentation and subject to change.]

The get_Terminal method gets an ITTerminal interface pointer for the terminal object involved in the event.

HRESULT get_Terminal(
  ITTerminal ** ppTerminal
);

Parameters

ppTerminal
[out,retval] Pointer to the ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTTSTerminalEvent, ITTerminal


Call Center Controls Overview

A call center is a location with agents or operators at banks of telephones either making outgoing telephone calls or fielding incoming ones. For example, a bank or credit card company uses a call center to process account inquiries.

TAPI 3.0 implements objects, interfaces, and methods that assist the programmer in creating call center applications. From a programming point of view, call center operations using TAPI are represented by the following diagram:

A programmer interested in creating call center applications may also want to consult the TAPI 2.2 functions that can enable portions of a call center suite. See TAPI 2.2 Call Center Control.


About TAPI 3.0 Call Center Controls

TAPI 3.0 defines five main ACD objects: the Agent Handler, the Queue, the ACD Group, the Agent, and the Agent Session. It also extends the TAPI object with an additional interface—ITTAPICallCenter.

Agent Object

The Agent object represents an agent capable of handling calls. This is usually a person but may be an IVR or some other combination of software and hardware. Agents are key to a call center; they are responsible for receiving and processing incoming calls and, at times, making outgoing calls to customers or prospects.

In TAPI, the Agent object directly relates to a Windows NT® user account, to provide compatibility with existing legacy switching systems. Additionally, to provide compatibility with existing legacy switching systems, the Agent may also be related to a switch agent ID.

The Agent object exposes the ITAgent interface. This interface implements methods that can create an Agent Session and retrieve statistics such as total calls handled. Applications can use the Agent object to manipulate Agent State and determine global agent statistics.

Agent Handler Object

An Agent Handler represents software or hardware capable of passing calls to a group of agents. Typically, this is a proprietary switch connecting outside lines to telephones at agent stations. Most ACD systems have only one such switch, but large operations may have more. In the case where an agent has devices on more than one ACD system, the agent will see a corresponding number of Agent Handler objects. There will also be an instance of the Agent object relating to the agent's appearance on each ACD system.

The Agent Handler object exposes the ITAgentHandler interface. This interface implements methods that provide information on the ACD Groups associated with the Agent Handler and the addresses that it can use.

Agent Session Object

An Agent Session represents an agent who has logged in and is qualified to handle calls for a particular ACD Group. An Agent Session is a dynamically created object, which relates an agent to an ACD group, for which they will provide service, and also to the address, where they will receive calls (turret, station, phone, etc.). Applications can use the Agent Session object to track the agent activity within a particular ACD group.

The Agent Session object exposes the ITAgentSession interface. This interface implements methods that can retrieve information such as average talk time for a call.

ACD Group Object

An ACD Group represents a class of calls that requires a particular type of handling. For example, some incoming calls for a bank's call center may concern existing accounts and others may relate to new accounts. Some agents may have expertise in both areas but most will specialize in one. ACD Groups will be created to handle each type of call. An ACD group services one or more queues. As incoming calls are classified, they will be passed to queues associated with the relevant ACD Group. A call coming off the queue is passed to an agent who has created an Agent Session Object indicating they are able to handle calls from that ACD Group.

The ACD Group Object exposes the ITACDGroup interface. This interface implements methods that provide access to the queues associated with the current ACD Group.

Queue Object

The Queue object represents a point within the ACD system where calls are temporarily held pending action. The Queue object exposes the ITQueue interface. This interface implements methods that gather statistics on a queue, such the number of calls currently queued. The ACD Proxy uses this information to distribute calls to Agents and to produce administrative reports.

Access to a Queue object allows an application to read a variety of standard statistics relating to queue usage, but does not give it the ability to control calls on the queue. Only applications with access to the associated addresses and lines (typically the ACD proxy application) would be able to control the calls on the queue.

Most queues relate directly to an ACD Group Object, and will hold a call until an agent can handle it. Other queues may exist to allow for complex call guides (the defined path an unanswered call will take through a switch). For example, calls may be placed in holding queues before being routed to a queue serviced by an ACD group.


Using TAPI 3.0 Call Center Controls

Call center controls extend the TAPI 3.0 object model to support the requirements of Automatic Call Distribution (ACD) systems. A call center is a location with agents or operators at banks of telephones either making outgoing telephone calls or fielding incoming ones. For example, a bank or credit card company will use a call center to process account inquiries.

Call center applications are divided into three basic types:

ACD Proxy : Handles incoming or outgoing sessions at the server, which can be anything from a proprietary telephone switch to an Internet gateway.

ACD Agent Client : Services an individual agent who is receiving or making calls.

ACD Supervisor Client: Provides an overall view of agent and ACD operations.

Note For Microsoft® Windows® 2000, proxy functionality is available using TAPI 2.2, and supervisor functions are not implemented.

The samples section of the Platform SDK contains ACD code samples under Netds\Tapi\Tapi2\Acd and Netds\Tapi\Tapi3\Acd.


ACD Proxy

An Automatic Call Distribution (ACD) server is a combination of hardware and software that classifies, queues, and distributes incoming calls to agents or outgoing calls to lines.

The Server ACD application is a TAPI proxy application, which for maximum efficiency should run on the same server as the telephony service provider (TSP). With a traditional ACD switch, the proxy application would interface to the switch's internal ACD and expose its operation. A software-based or "virtual" ACD proxy application would be fully responsible for the tracking of calls, queues, groups, and agents and would use the standard TAPI interfaces to control the switching hardware. Agent client applications will typically run on the individual agent's workstations and make use of the TAPI Remote Service Provider to communicate with the TAPISRV on the server machine, and hence the proxy application.

Classification of incoming calls is designed to get a call to an agent who will be able to handle it effectively. Classification may be based on the number dialed, an interactive voice recognition (IVR) system, or other criteria. TAPI uses the concept of an ACD Group to represent this operation.

Queues are a graceful and expected way for call centers to deal with heavy load periods. A queue is normally associated with an ACD Group but may be created to handle outgoing lines or incoming calls waiting for an IVR application. See Queues for more information.

Call distribution to agents or groups of agents may be uniform but typically is based on data such as call information, agent availability, and ability. TAPI's Agent Handler provides access to information such as agent availability and addresses for the transfer of calls to agents.

In addition to basic call distribution, an ACD system provides for managing and reporting on the system performance. Statistics gathered on call queues, groups, and agents are used to refine and enhance the performance of the system and are typically used as the basis for Agent remuneration.


ACD Agent Client

A call center agent is responsible for receiving and processing incoming calls and, at times, making outgoing calls to customers or prospects. An ACD Agent Client application supplies communications with the ACD Proxy application, providing it with information such as whether the agent is available for calls and what types of calls the agent can handle. The following diagram illustrates how TAPI objects look to an agent.

Call Center Controls Reference

The Call Center Control reference material contains information on interfaces, methods, and enumerators used in TAPI 3 call center controls.

You may also wish to search the Platform SDK for information on call and media controls. COM is the basic coding model for TAPI 3.0, and familiarity with it is assumed throughout this document.

Call Center Controls Quick Reference

Call Center Controls Interfaces

Call Center Controls Enumerations


Call Center Controls Quick Reference

The following table lists the TAPI 3 COM interfaces for the call center controls, events, and enumerators.

Interface groupings | Description
Call Center Interfaces | The Call Center objects represent the Automatic Call Distribution groups, agents, agent handlers, agent sessions, and queue involved in call center operations. The associated interfaces and methods get and set information concerning the call center, such as total calls handled by an agent during a session.
Call Center Enumerator Interfaces | COM-standard enumerator interfaces.
Call Center Event Interfaces | The call center event interfaces.
ITTAPICallCenter | Provides an entry interface into call center controls from the TAPI object.


Call Center Controls Interfaces

The call center interfaces provide methods that queue and distribute calls within a call center. TAPI 3.0 defines five main call center objects: ACDGroup, Agent, AgentHandler, AgentSession, and Queue. All of these objects can be extended to provide implementation-specific methods. In addition, the ITTAPICallCenter interface on the TAPI object provides methods to enumerate AgentHandler objects.

See About TAPI 3.0 Call Center Controls for additional information.

Interface | Description
ITACDGroup | Gets name and queue information for an ACD group.
ITACDGroupEvent | Gets description of ACD group events.
ITAgent | Provides methods to set and get information concerning an agent.
ITAgentEvent | Notification interface for ITAgent.
ITAgentHandler | Provides methods to create Agent objects and enumerate ACD groups.
ITAgentHandlerEvent | Gets description of AgentHandler events.
ITAgentSession | Provides methods to set and get information concerning an agent session.
ITAgentSessionEvent | Notification interface for ITAgentSession.
ITQueue | Gets and sets information concerning a queue.
ITQueueEvent | Gets information concerning a queue event.
IEnumACDGroup | Enumerates ITACDGroup.
IEnumAgent | Enumerates ITAgent.
IEnumAgentHandler | Enumerates ITAgentHandler.
IEnumAgentSession | Enumerates ITAgentSession.
IEnumQueue | Enumerates ITQueue.


Call Center Enumerator Interfaces

The following interfaces enumerate TAPI 3.0 elements according to COM standards. These interfaces constitute stand-alone objects, and are also summarized with their related objects.

IEnumACDGroup | Enumerates ITACDGroup.
IEnumAgent | Enumerates ITAgent.
IEnumAgentHandler | Enumerates ITAgentHandler.
IEnumAgentSession | Enumerates ITAgentSession.
IEnumQueue | Enumerates ITQueue.


Call Center Event Interfaces

The event (notification) interfaces allow a TAPI 3.0 application to respond to asynchronous events.

You must call the ITTAPI::put_EventFilter method and set an event filter mask to enable reception of request events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events.

Please see the Events overview for a description of how an application ensures reception of notifications. See the individual interfaces listed in the following table for more information about setting a filter mask for individual event types.

ITACDGroupEvent | Retrieves the description of Automatic Call Distribution (ACD) group events.
ITAgentEvent | Retrieves the description of agent events.
ITAgentHandlerEvent | Retrieves the description of agent handler events.
ITAgentSessionEvent | Retrieves the description of agent session events.


Call Center Controls Enumerations

TAPI 3.0 call center controls use the following enumerations to set and report on events and states.

ACDGROUP_EVENT

ACDQUEUE_EVENT

AGENT_EVENT

AGENTHANDLER_EVENT

AGENT_SESSION_EVENT

AGENT_SESSION_STATE

AGENT_STATE


ACDGROUP_EVENT

The ACDGROUP_EVENT enum describes ACD group events. The ITACDGroupEvent::get_Event method returns a member of this enum to indicate the type of ACD group event that occurred.

typedef enum ACDGROUP_EVENT
{
  ACDGE_NEW_GROUP,
  ACDGE_GROUP_REMOVED
} ACDGROUP_EVENT;

Members

ACDGE_NEW_GROUP
A new ACD group has been added.
ACDGE_GROUP_REMOVED
An ACD group has been removed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITACDGroupEvent::get_Event


ACDQUEUE_EVENT

The ACDQUEUE_EVENT enum describes ACD queue events. The ITQueueEvent::get_Event method returns a member of this enum to indicate the type of ACD queue event that occurred.

typedef enum ACDQUEUE_EVENT
{
  ACDQE_NEW_QUEUE,
  ACDQE_QUEUE_REMOVED
} ACDQUEUE_EVENT;

Members

ACDQE_NEW_QUEUE
A new ACD queue has been added.
ACDQE_QUEUE_REMOVED
An ACD queue has been removed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITCallNotificationEvent::get_Event, ITCallNotificationEvent, ITQueueEvent::get_Event


AGENT_EVENT

The AGENT_EVENT enum describes agent events. The ITAgentEvent::get_Event method returns a member of this enum to indicate the type of agent event that occurred.

typedef enum AGENT_EVENT
{
  AE_NOT_READY,
  AE_READY,
  AE_BUSY_ACD,
  AE_BUSY_INCOMING,
  AE_BUSY_OUTGOING,
  AE_UNKNOWN,
} AGENT_EVENT;

Members

AE_NOT_READY
The agent is unable to handle calls.
AE_READY
The agent is able to handle calls.
AE_BUSY_ACD
The agent is active handling an ACD call.
AE_BUSY_INCOMING
The agent is active handling an incoming non-ACD call.
AE_BUSY_OUTGOING
The agent is active handling an outgoing non-ACD call.
AE_UNKNOWN
Unknown state.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAgentEvent::get_Event, ITCallNotificationEvent


AGENTHANDLER_EVENT

The AGENTHANDLER_EVENT enum describes agent handler events. The ITAgentHandlerEvent::get_Event method returns a member of this enum to indicate the type of agent handler event that occurred.

typedef enum AGENTHANDLER_EVENT
{
  AHE_NEW_AGENTHANDLER,
  AHE_AGENTHANDLER_REMOVED
} AGENTHANDLER_EVENT;

Members

AHE_NEW_AGENTHANDLER
A new AgentHandler object has been added.
AHE_AGENTHANDLER_REMOVED
An AgentHandler object has been removed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAgentHandlerEvent::get_Event, ITCallNotificationEvent


AGENT_SESSION_EVENT

The AGENT_SESSION_EVENT enum describes agent session events. The ITAgentSessionEvent::get_Event method returns a member of this enum to indicate the type of agent session event that occurred.

typedef enum AGENT_SESSION_EVENT
{
  ASE_NEW_SESSION,
  ASE_NOT_READY,
  ASE_READY,
  ASE_BUSY,
  ASE_WRAPUP,
  ASE_END
} AGENT_SESSION_EVENT;

Members

ASE_NEW_SESSION
A new agent session has been created.
ASE_NOT_READY
The agent is unable to handle calls for this session.
ASE_READY
The agent is able to handle calls for this session.
ASE_BUSY
The agent is active in this session handling an ACD call.
ASE_WRAPUP
The agent is active in this session handling the wrap-up of an ACD call.
ASE_END
The session has completed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAgentSessionEvent::get_Event, ITCallNotificationEvent


AGENT_SESSION_STATE

This AGENT_SESSION_STATE enum defines the agent session indicators used by the ITAgentSession::get_State and the ITAgentSession::put_State methods.

typedef enum AGENT_SESSION_STATE
{
  ASST_NOT_READY,
  ASST_READY,
  ASST_BUSY_ON_CALL,
  ASST_BUSY_WRAPUP,
  ASST_SESSION_ENDED
}  AGENT_SESSION_STATE;

Members

ASST_NOT_READY
The agent is unable to handle calls for this session.
ASST_READY
The agent is able to handle calls for this session.
ASST_BUSY_ON_CALL
The agent is active in this session handling an ACD call.
ASST_BUSY_WRAPUP
The agent is active in this session handling the wrap-up of an ACD call.
ASST_SESSION_ENDED
The session has completed.

Following is a table of all valid AgentSession state transitions.

From state | To state
ASST_NOT_READY | ASST_READY ASST_SESSION_ENDED
ASST_READY | ASST_BUSY_ON_CALL ASST_NOT_READY ASST_SESSION_ENDED
ASST_BUSY_ON_CALL | ASST_BUSY_WRAPUP ASST_READY ASST_NOT_READY ASST_SESSION_ENDED
ASST_BUSY_WRAPUP | ASST_READY ASST_NOT_READY ASST_SESSION_ENDED

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAgentSession::get_State, ITAgentSession::put_State


AGENT_STATE

The AGENT_STATE enum is used by the ITAgent::put_State and ITAgent::get_State methods to describe the agent state.

typedef enum AGENT_STATE
{
  AS_NOT_READY,
  AS_READY,
  AS_BUSY_ACD,
  AS_BUSY_INCOMING,
  AS_BUSY_OUTGOING,
  AS_UNKNOWN
}  AGENT_STATE;

Members

AS_NOT_READY
Agent is not ready
AS_READY
Agent is ready
AS_BUSY_ACD
Agent is busy with an ACD call.
AS_BUSY_INCOMING
Agent has a call incoming.
AS_BUSY_OUTGOING
Agent has a call that is outgoing.
AS_UNKNOWN
Agent state unknown.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

ITAgent::get_State, ITAgent::put_State


TAPI 3 Call Center Controls COM Interfaces

This section contains an alphabetic listing of the TAPI 3.0 call center controls interfaces.


IEnumACDGroup

The IEnumACDGroup interface provides COM-standard enumeration methods for the ITACDGroup interface. The ITAgentHandler::EnumerateACDGroups method returns a pointer to IEnumACDGroup.

Methods in Vtable Order

IUnknown Methods

IEnumACDGroup methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITACDGroup


IEnumACDGroup::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumACDGroup **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumACDGroup interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumACDGroup, ITACDGroup


IEnumACDGroup::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITACDGroup **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out] Pointer to ITACDGroup list of pointers returned.
pceltFetched
[in,out,ptr] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppElements parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumACDGroup, ITACDGroup


IEnumACDGroup::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumACDGroup, ITACDGroup


IEnumACDGroup::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumACDGroup, ITACDGroup


IEnumAgent

Enumerator interface for ITAgent.

Methods in Vtable Order

IUnknown Methods

IEnumAgent methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


IEnumAgent::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumAgent **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumAgent interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgent, ITAgent


IEnumAgent::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITAgent **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out] Pointer to ITAgent pointer.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgent, ITAgent


IEnumAgent::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgent, ITAgent


IEnumAgent::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgent, ITAgent


IEnumAgentHandler

The IEnumAgentHandler interface provides COM-standard enumeration methods for the ITAgentHandler interface. The ITTAPICallCenter::EnumerateAgentHandlers method returns a pointer to IEnumAgentHandler.

Methods in Vtable Order

IUnknown Methods

IEnumAgentHandler methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumAgentHandler::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumAgentHandler **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumAgentHandler interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentHandler


IEnumAgentHandler::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITAgentHandler **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt), size_is(celt)] Pointer to ITAgentHandler interfaces.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentHandler


IEnumAgentHandler::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentHandler


IEnumAgentHandler::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentHandler


IEnumAgentSession

The IEnumAgentSession interface provides COM-standard enumeration methods for the ITAgentSession interface. The ITAgent::EnumerateAgentSessions method returns a pointer to IEnumAgentSession.

Methods in Vtable Order

IUnknown Methods

IEnumAgentSession methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumAgentSession::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumAgentSession **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumAgentSession interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentSession


IEnumAgentSession::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITAgentSession **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITAgentSession interface.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentSession


IEnumAgentSession::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentSession


IEnumAgentSession::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

IEnumAgentSession


IEnumQueue

The IEnumQueue interface provides COM-standard enumeration methods for the ITQueue interface. The ITACDGroup::EnumerateQueues method returns a pointer to IEnumQueue.

Methods in Vtable Order

IUnknown Methods

IEnumQueue methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumQueue::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumQueue **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumQueue interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumQueue::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITQueue **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITQueue list of interface pointers returned.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumQueue::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset(void);

Parameters

None

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


IEnumQueue::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITACDGroup

Automatic Call Distribution (ACD) is a mechanism that queues and distributes calls within a switching system. The ACDGroup object reflects an ACD pilot, split, or group. For example, one ACDGroup might handle calls for new accounts while another handles queries on existing accounts.

See About TAPI 3.0 Call Center Controls for additional information.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITACDGroup methods | Description
get_Name | Gets the ACD group name.
EnumerateQueues | Enumerates queues currently on the ACD group.
get_Queues | Creates a collection of queues associated with the current ACD group. Provided for Automation client applications, such as those written in Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITACDGroup::EnumerateQueues

The EnumerateQueues method enumerates queues currently on the ACD group. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_Queues method.

HRESULT EnumerateQueues(
  IEnumQueue **ppEnumQueue
);

Parameters

ppEnumQueue
[out] Pointer to IEnumQueue interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppEnumQueue parameter is not a valid pointer.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITACDGroup, get_Queues, IEnumQueue


ITACDGroup::get_Name

The get_Name method gets the ACD group name. This string can be a displayable name for the group.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out, retval] Pointer to BSTR representation of group name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must free ppName through SysFreeString when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITACDGroup


ITACDGroup::get_Queues

The get_Queues method creates a collection of queues associated with the current ACD group. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateQueues method.

HRESULT get_Queues(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITQueue interface pointers (queue objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITACDGroup, EnumerateQueues, ITQueue, ITCollection


ITACDGroupEvent

The ITACDGroupEvent interface contains methods that retrieve the description of Automatic Call Distribution (ACD) group events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_ACDGROUP, the method's pEvent parameter is an IDispatch pointer for the ITACDGroupEvent interface. The methods of this interface can be used to retrieve information concerning the ACD group change that has occurred.

See About TAPI 3.0 Call Center Controls for additional information concerning ACD groups.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_ACDGROUP event to enable reception of ACD group events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITACDGroupEvent methods | Description
get_Group | Gets a pointer to the ITACDGroup interface.
get_Event | Gets the ACDGROUP_EVENT descriptor of an event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITACDGroup, ACDGROUP_EVENT, Register Events code snippet


ITACDGroupEvent::get_Event

The get_Event method gets the descriptor of an event which indicates that a new ACD group has been added.

HRESULT get_Event(
  ACDGROUP_EVENT *pEvent
);

Parameters

pEvent
[out, retval] Pointer to ACDGROUP_EVENT descriptor of event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pEvent parameter is not a valid pointer.

Remarks

The ACDGE_NEW_GROUP and ACDGE_REMOVE_GROUP values are not currently supported.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITACDGroupEvent, ACDGROUP_EVENT


ITACDGroupEvent::get_Group

The get_Group method gets the ITACDGroup interface pointer for the group on which the event occurred.

HRESULT get_Group(
  ITACDGroup **ppGroup
);

Parameters

ppGroup
[out, retval] Pointer to ITACDGroup interface on which the event occurred.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppGroup parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITACDGroupEvent, ITACDGroup


ITAgent

Agents are the heart of a call center. They are responsible for receiving and processing incoming calls and, at times, making outgoing calls to customers or prospects. See About TAPI 3.0 Call Center Controls for additional information.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAgent methods | Description
EnumerateAgentSessions | Enumerates the current agent sessions.
CreateSession | Creates a new agent session.
CreateSessionWithPIN | Creates a new agent session, with Personal Identification Number (PIN).
get_ID | Gets an agent's ID.
get_User | Gets the agent user name.
get_State | Gets the state of an agent session.
put_State | Sets the state of an agent session.
get_MeasurementPeriod | Gets the period (in seconds) for which the switch and/or implementation stores and calculates information.
put_MeasurementPeriod | Sets the period (in seconds) for which the switch and/or implementation stores and calculates information.
get_OverallCallRate | Gets the agent call rate across all sessions.
get_NumberOfACDCalls | Gets the number of ACD calls handled by this agent across all sessions.
get_NumberOfIncomingCalls | Gets the number of incoming non-ACD calls handled by this agent.
get_NumberOfOutgoingCalls | Gets the number of outgoing non-ACD calls handled by this agent.
get_TotalACDTalkTime | Gets the number of seconds spent talking in ACD calls by this agent (across all sessions).
get_TotalACDCallTime | Gets the number of seconds spent on ACD calls by this agent, including wrap-up time.
get_TotalWrapUpTime | Gets the number of seconds spent on ACD wrap-up work by this agent.
get_AgentSessions | Creates a collection of current agent sessions. This method is provided for Automation client applications, such as those written in Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

About TAPI 3.0 Call Center Controls


ITAgent::CreateSession

The CreateSession method creates a new agent session for the input ACD group and address.

HRESULT CreateSession(
  ITACDGroup *pACDGroup,
  ITAddress *pAddress,
  ITAgentSession **ppAgentSession
);

Parameters

pACDGroup
[in] Pointer to ITACDGroup interface.
pAddress
[in] Pointer to ITAddress object available for receiving ACD calls.
ppAgentSession
[out, retval] Pointer to ITAgentSession interface for object created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppAgentSession parameter is not a valid pointer.
E_UNEXPECTED | Failed to open a line for the target Address.
E_INVALIDARG | The pACDGroup or pAddress argument is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Some telephone environments require a personal identification number to open a session. See CreateSessionWithPIN.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, ITACDGroup, ITAddress, ITAgentSession, IEnumAgentSession, ITAgent::CreateSessionWithPIN


ITAgent::CreateSessionWithPIN

The CreateSessionWithPIN method creates a new agent session for the input ACD group and address, with Personal Identification Number (PIN).

HRESULT CreateSessionWithPIN(
  ITACDGroup *pACDGroup,
  ITAddress *pAddress,
  BSTR pPIN,
  ITAgentSession **ppAgentSession
);

Parameters

pACDGroup
[in] Pointer to ITACDGroup interface.
pAddress
[in] Pointer to ITAddress interface for object available for receiving ACD calls.
pPIN
[in] Pointer to a BSTR representation of agent's PIN.
ppAgentSession
[out, retval] Pointer to session created.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_CALLCENTER_NO_AGENT_ID | Agent not created by CreateAgentWithID.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.
E_INVALIDARG | pPIN is NULL.
E_POINTER | The pPIN or ppAgentSession parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysAllocString to allocate memory for pPIN and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, ITAgentSession, ITAgent::CreateSession


ITAgent::EnumerateAgentSessions

The EnumerateAgentSessions method enumerates the current agent sessions. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_AgentSessions method.

HRESULT EnumerateAgentSessions(
  IEnumAgentSession **ppEnumAgentSession
);

Parameters

ppEnumAgentSession
[out, retval] Pointer to an IEnumAgentSession agent session enumerator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumAgentSession parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, ITAgentSession, IEnumAgentSession, ITAgent::CreateSession, ITAgent::CreateSessionWithPIN, get_AgentSessions


ITAgent::get_AgentSessions

The get_AgentSessions method creates a collection of current agent sessions. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateAgentSessions method.

HRESULT get_AgentSessions(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITAgentSession interface pointers (agent session objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, ITAgentSession, EnumerateAgentSessions, ITCollection, ITAgentSession


ITAgent::get_ID

The get_ID method gets an agent's ID.

HRESULT get_ID(
  BSTR *ppID
);

Parameters

ppID
[out, retval] Pointer to BSTR containing agent ID.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_CALLCENTER_NO_AGENT_ID | ITAgent was not created using ITAgentHandler::CreateAgentWithID, but with ITAgentHandler::CreateAgent. No ID exists.
E_POINTER | The ppID parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

This method is provided for interfacing with legacy switch solutions.

The application must free the memory allocated for the ppID parameter through SysFreeString when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_MeasurementPeriod

The get_MeasurementPeriod method gets the measurement period (in seconds) for which the switch and/or implementation stores and calculates information. For example, get_NumberOfACDCalls returns the number of calls the agent handled; get_MeasurementPeriod indicates if this value referenced the calls handled in the last hour, day, month, etc.

HRESULT get_MeasurementPeriod(
  long *plPeriod
);

Parameters

plPeriod
[out, retval] Measurement period.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plPeriod parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, put_MeasurementPeriod


ITAgent::get_NumberOfACDCalls

The get_NumberOfACDCalls method gets the number of ACD calls handled by this agent across all sessions.

The measurement period over which this information is calculated is switch- and/or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_NumberOfACDCalls(
  long *plCalls
);

Parameters

plCalls
[out, retval] Total number of calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_NumberOfIncomingCalls

The get_NumberOfIncomingCalls method gets the number of incoming non-ACD calls handled by this agent.

The measurement period over which this information is calculated is switch- and/or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_NumberOfIncomingCalls(
  long *plCalls
);

Parameters

plCalls
[out, retval] Total number of incoming calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_NumberOfOutgoingCalls

The get_NumberOfOutgoingCalls method gets the number of outgoing non-ACD calls handled during by this agent.

The measurement period over which this information is calculated is switch- and/or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_NumberOfOutgoingCalls(
  long *plCalls
);

Parameters

plCalls
[out, retval] Total number of outgoing calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_OverallCallRate

The get_OverallCallRate method gets an agent's call rate across all sessions. 10 *Calls per agent hour (where agent hour represents the time that an agent was active in one or more agent sessions).

The measurement period over which this information is calculated is switch- and/or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_OverallCallRate(
  CURRENCY *pcyCallrate
);

Parameters

pcyCallrate
[out, retval] Call rate.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pcyCallrate parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

The CURRENCY type is used here instead of FLOAT for Visual Basic and Java compatibility.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_State

The get_State method gets the state of an agent session.

HRESULT get_State(
  AGENT_STATE *pAgentState
);

Parameters

pAgentState
[out, retval] Pointer to an AGENT_STATE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pAgentState parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, put_State, AGENT_STATE


ITAgent::get_TotalACDCallTime

The get_TotalACDCallTime gets the number of seconds spent on ACD calls by this agent (across all sessions). This value includes the time spent on the phone plus wrap-up time.

The measurement period over which this information is calculated is switch- and/or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_TotalACDCallTime (
  long *plCallTime
);

Parameters

plCallTime
[out, retval] Total call time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCallTime parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_TotalACDTalkTime

The get_TotalACDTalkTime gets the number of seconds spent talking in ACD calls by this agent (across all sessions).

The measurement period over which this information is calculated is switch- and/or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_TotalACDTalkTime(
  long *plTalkTime
);

Parameters

plTalkTime
[out, retval] Total talk time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plTalkTime parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_TotalWrapUpTime

The get_TotalWrapUpTime method gets the number of seconds spent on ACD call wrap-up (after-call work) by this agent (across all sessions).

The measurement period over which this information is calculated is switch and/or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_TotalWrapUpTime(
  long *plWrapUpTime
);

Parameters

plWrapUpTime
[out, retval] Total wrap-up time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plWrapUpTime parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::get_User

The get_User method gets the agent user name, which is the same as the operating system user login or e-mail name.

HRESULT get_User(
  BSTR *ppUser
);

Parameters

ppUser
[out, retval] Pointer to BSTR containing user name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppUser parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must free the memory allocated for the ppUser parameter through SysFreeString when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent


ITAgent::put_MeasurementPeriod

The put_MeasurementPeriod method sets the period (in seconds) for which the switch and/or implementation stores and calculates information. This also resets any cumulative counts to zero.

HRESULT put_MeasurementPeriod(
  long lPeriod
);

Parameters

lPeriod
[in] Measurement period (in seconds).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | Value of lPeriod is zero.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
LINEERR_ | See lineSetAgentMeasurementPeriod for error codes returned from this TAPI 2.1 function.

Remarks

The ITAgent::put_MeasurementPeriod method is a COM wrapper for the TAPI 2.1 lineSetAgentMeasurementPeriod function.

This method will accept negative values for the measurement period, but this will normally result in unreliable statistics.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, get_MeasurementPeriod


ITAgent::put_State

The put_State method sets the state of an agent session.

HRESULT put_State(
  AGENT_STATE AgentState
);

Parameters

AgentState
[in] AGENT_STATE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | Agent session state is incorrect.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

The ITAgent::put_State method is a COM wrapper for the TAPI 2.1 lineSetAgentStateEx function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, get_State, AGENT_STATE


ITAgentEvent

The ITAgentEvent interface contains methods that retrieve the description of agent events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_AGENT, the method's pEvent parameter is an IDispatch pointer for the ITAgentEvent interface. The methods of this interface can be used to retrieve information concerning the agent event that has occurred.

See About TAPI 3.0 Call Center Controls for additional information on agents.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_AGENT event to enable reception of agent events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAgentEvent methods | Description
get_Agent | Gets a pointer to the ITAgentinterface.
get_Event | Gets the AGENT_EVENT descriptor of an event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITAgent, AGENT_EVENT, About TAPI 3.0 Call Center Controls, Register Events code snippet


ITAgentEvent::get_Agent

The get_Agent method gets the interface for the agent on which the event occurred.

HRESULT get_Agent(
  ITAgent **ppAgent
);

Parameters

ppAgent
[out, retval] Pointer to ITAgent interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppAgent parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentEvent


ITAgentEvent::get_Event

Gets an AGENT_EVENT descriptor of the event that occurred.

HRESULT get_Event(
  AGENT_EVENT *pEvent
);

Parameters

pEvent
[out, retval] Pointer to AGENT_EVENT descriptor of event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pEvent parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentEvent, AGENT_EVENT


ITAgentHandler

The ITAgentHandler interface provides methods to create Agent objects and enumerate Automatic Call Distribution (ACD) groups.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAgentHandler methods | Description
get_Name | Gets the agent handler name.
CreateAgent | Creates an Agent object.
CreateAgentWithID | Creates an Agent object based on an agent identifier.
EnumerateACDGroups | Enumerates ACD groups currently associated with the agent handler.
EnumerateUsableAddresses | Enumerates addresses available for receiving ACD calls on this agent handler.
get_ACDGroups | Creates a collection of ACD groups currently associated with the agent handler. This method is provided for Automation client applications, such as those written in Visual Basic.
get_UsableAddresses | Creates a collection of addresses available for receiving ACD calls on this agent handler. This method is provided for Automation client applications, such as those written in Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgent, About TAPI 3.0 Call Center Controls


ITAgentHandler::CreateAgent

The CreateAgent method creates an Agent object.

HRESULT CreateAgent(
  ITAgent **ppAgent
);

Parameters

ppAgent
[out, retval] Pointer to the ITAgent interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppAgent parameter is not a valid pointer.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler, CreateAgentWithID


ITAgentHandler::CreateAgentWithID

The CreateAgentWithID method creates an Agent object based on an agent identifier. This identifier is a string identifying the agent on a legacy ACD system. If the system also requires a PIN or password for logging into groups, you use this method to set the PIN or password.

HRESULT CreateAgentWithID(
  BSTR pID,
  BSTR pPIN,
  ITAgent **ppAgent
);

Parameters

pID
[in] Pointer to BSTR containing the agent identifier.
pPIN
[in] Pointer to BSTR containing the agent PIN.
ppAgent
[out, retval] Pointer to ITAgent interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pPIN parameter is NULL.
E_POINTER | The ppAgent parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

The application must use SysAllocString to allocate memory for the pID and pPIN parameters, and use SysFreeString to free the memory when the variables are no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler, CreateAgent


ITAgentHandler::EnumerateACDGroups

The EnumerateACDGroups method enumerates ACD groups currently associated with the agent handler. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_ACDGroups method. The number of groups returned is based upon replies from the ACD proxy application. Each proxy application will return a list of groups according to its own internal privilege/security decisions.

HRESULT EnumerateACDGroups(
  IEnumACDGroup **ppEnumACDGroup
);

Parameters

ppEnumACDGroup
[out, retval] Pointer to IEnumACDGroup interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppEnumACDGroup parameter is not a valid pointer.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler, IEnumACDGroup


ITAgentHandler::EnumerateUsableAddresses

The EnumerateUsableAddresses method enumerates addresses available for receiving ACD calls on this agent handler. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_UsableAddresses method.

HRESULT EnumerateUsableAddresses(
  IEnumAddress **ppEnumAddress
);

Parameters

ppEnumAddress
[out, retval] Pointer to IEnumAddress interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppEnumAddress parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler, EnumerateUsableAddresses


ITAgentHandler::get_ACDGroups

The get_ACDGroups method creates a collection of ACD groups currently associated with the agent handler. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateACDGroups method.

HRESULT get_ACDGroups(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITACDGroup interface pointers (ACD group objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler, EnumerateACDGroups, ITCollection, ITACDGroup


ITAgentHandler::get_Name

The get_Name method gets the agent handler name.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out, retval] Pointer to BSTR representation of the agent handler name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppName parameter is not a valid pointer.

Remarks

The application must free the memory allocated for the ppName parameter through SysFreeString when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler


ITAgentHandler::get_UsableAddresses

The get_UsableAddresses method creates a collection of addresses available for receiving ACD calls on this agent handler. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateUsableAddresses method.

HRESULT get_UsableAddresses(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITAddress interface pointers (address objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler, EnumerateUsableAddresses, ITCollection, ITAddress


ITAgentHandlerEvent

The ITAgentHandlerEvent interface contains methods that retrieve the description of agent handler events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_AGENTHANDLER, the method's pEvent parameter is an IDispatch pointer for the ITAgentHandlerEvent interface. The methods of this interface can be used to retrieve information concerning the agent handler change that has occurred.

See About TAPI 3.0 Call Center Controls for additional information.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_AGENTHANDLER event to enable reception of agent handler events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAgentHandlerEvent methods | Description
get_AgentHandler | Gets a pointer to the ITAgentHandler interface.
get_Event | Gets the AGENTHANDLER_EVENT descriptor of the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandler, ITAgent, About TAPI 3.0 Call Center Controls, ITTAPIEventNotification::Event, TAPI_EVENT, AGENTHANDLER_EVENT, Register Events code snippet


ITAgentHandlerEvent::get_AgentHandler

The get_AgentHandler method gets the ITAgentHandler interface pointer.

HRESULT get_AgentHandler(
  ITAgentHandler **ppAgentHandler
);

Parameters

ppAgentHandler
[out, retval] Pointer to the ITAgentHandler interface on which the event occurred.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppAgentHandler parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandlerEvent


ITAgentHandlerEvent::get_Event

The get_Event method gets the description for the event that has occurred.

HRESULT get_Event(
  AGENTHANDLER_EVENT *pEvent
);

Parameters

pEvent
[out, retval] Pointer to the AGENTHANDLER_EVENT descriptor.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pEvent parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentHandlerEvent, AGENTHANDLER_EVENT


ITAgentSession

An agent session represents an association between an agent, group, and address. The methods of ITAgentSession allow an application to retreive a variety of statistics.

See About TAPI 3.0 Call Center Controls for additional information.

Note to TAPI 2.1 programmers: Many of the methods in this interface are COM wrappers for lineGetAgentSessionInfo.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAgentSession methods | Description
get_Agent | Gets the ITAgent associated with this session.
get_Address | Gets the ITAddress associated with this session.
get_ACDGroup | Gets the ITACDGroup associated with this session.
get_State | Gets the current AGENT_SESSION_STATE of session.
put_State | Sets the AGENT_SESSION_STATE of the session.
get_SessionStartTime | Gets the time that a session was created.
get_SessionDuration | Gets the duration of the Agent session in seconds.
get_NumberOfCalls | Gets the number of ACD calls handled by this agent during this session.
get_TotalTalkTime | Gets the number of seconds spent by this agent talking in ACD calls during this session.
get_AverageTalkTime | Gets the average time (in seconds) spent talking per ACD call by this agent during this session.
get_TotalCallTime | Gets the number of seconds spent on ACD calls during this agent session by this agent, including wrap-up time.
get_AverageCallTime | Gets the average time (in seconds) spent per ACD call by this agent during this session, including wrap-up time.
get_TotalWrapUpTime | Gets the number of seconds spent on ACD call wrap-up during this agent session by this agent.
get_AverageWrapUpTime | Gets the average time (in seconds) spent on ACD call wrap-up during this agent session by this agent.
get_ACDCallRate | Gets the ACD call rate per agent session.
get_LongestTimeToAnswer | Gets the longest time (in seconds) a call was waiting to be answered.
get_AverageTimeToAnswer | Gets the average time (in seconds) a call was waiting to be answered.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

About TAPI 3.0 Call Center Controls


ITAgentSession::get_ACDCallRate

The get_ACDCallRate method gets the all rate per agent session, in calls per hour.

HRESULT get_ACDCallRate(
  CURRENCY *pcyCallrate
);

Parameters

pcyCallrate
[out, retval] Pointer to call rate.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pcyCallrate parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_ACDGroup

The get_ACDGroup method gets the ACD group associated with this session.

HRESULT get_ACDGroup(
  ITACDGroup **ppACDGroup
);

Parameters

ppACDGroup
[out, retval] Pointer to ITACDGroup interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppACDGroup parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_Address

The get_Address method gets a pointer to the ITAddress interface associated with this session.

HRESULT get_Address(
  ITAddress **ppAddress
);

Parameters

ppAddress
[out, retval] Pointer for ITAddress.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppAddress parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession


ITAgentSession::get_Agent

The get_Agent method gets a pointer to the ITAgent interface associated with this session.

HRESULT get_Agent(
  ITAgent **ppAgent
);

Parameters

ppAgent
[out, retval] pointer to ITAgent interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppAgent parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession


ITAgentSession::get_AverageCallTime

The get_AverageCallTime method gets the average time (in seconds) spent per ACD call during this agent session. This value includes the time spent on the phone plus wrap-up time.

HRESULT get_AverageCallTime(
  long *plCallTime
);

Parameters

plCallTime
[out, retval] Pointer to the average call time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCallTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_AverageTalkTime

The get_AverageTalkTime method gets the average time (in seconds) spent talking per ACD call, during this agent session (by this agent).

HRESULT get_AverageTalkTime(
  long *plTalkTime
);

Parameters

plTalkTime
[out, retval] Average talk time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plTalkTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_AverageTimeToAnswer

The get_AverageTimeToAnswer method gets the average time (in seconds) that calls waited to be answered.

HRESULT get_AverageTimeToAnswer(
  long *plAnswerTime
);

Parameters

plAnswerTime
[out, retval] Pointer to average time to answer a call.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plAnswerTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_AverageWrapUpTime

The get_AverageWrapUpTime method gets the average time (in seconds) per ACD call spent in wrap-up (after-call work) during this agent session.

HRESULT get_AverageWrapUpTime(
  long *plWrapUpTime
);

Parameters

plWrapUpTime
[out, retval] Pointer to average wrap-up time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plWrapUpTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession


ITAgentSession::get_LongestTimeToAnswer

The get_LongestTimeToAnswer method gets the longest time (in seconds) a call was waiting to be answered.

HRESULT get_LongestTimeToAnswer(
  long *plAnswerTime
);

Parameters

plAnswerTime
[out, retval] Pointer to longest time to answer a call.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plAnswerTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_NumberOfCalls

The get_NumberOfCalls method gets the number of ACD calls handled by this agent during this session.

HRESULT get_NumberOfCalls(
  long *plCalls
);

Parameters

plCalls
[out, retval] Pointer to total number of calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCalls parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_SessionDuration

The get_SessionDuration method gets the duration of the Agent session in seconds. This duration is for the active period only; timing stops when a session enters the ASST_SESSION_ENDED state of AGENT_SESSION_STATE.

HRESULT get_SessionDuration(
  long *plDuration
);

Parameters

plDuration
[out, retval] Pointer to session duration.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plDuration parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_SessionStartTime

The get_SessionStartTime method gets the time that the session was created.

HRESULT get_SessionStartTime(
  DATE *pdateSessionStart
);

Parameters

pdateSessionStart
[out, retval] Pointer to session start time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pdateSessionStart parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_State

The get_State method gets the current state of this session.

HRESULT get_State(
  AGENT_SESSION_STATE *pSessionState
);

Parameters

pSessionState
[out, retval] Pointer to an AGENT_SESSION_STATE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pSessionState parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, put_State, AGENT_SESSION_STATE


ITAgentSession::get_TotalCallTime

The get_TotalCallTime method gets the number of seconds spent on ACD calls during this agent session (by this agent). This value includes the time spent on the phone plus wrap-up time.

HRESULT get_TotalCallTime(
  long *plCallTime
);

Parameters

plCallTime
[out, retval] Pointer to total call time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plCallTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_TotalTalkTime

The get_TotalTalkTime method gets the number of seconds spent by this agent talking in ACD calls during this session.

HRESULT get_TotalTalkTime(
  long *plTalkTime
);

Parameters

plTalkTime
[out, retval] Total talk time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plTalkTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::get_TotalWrapUpTime

The get_TotalWrapUpTime method gets the number of seconds spent on ACD call wrap-up (after-call work) during this agent session (by this agent).

HRESULT get_TotalWrapUpTime(
  long *plWrapUpTime
);

Parameters

plWrapUpTime
[out, retval] Pointer to total wrap-up time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The plWrapUpTime parameter is not a valid pointer.
LINEERR_ | See lineGetAgentSessionInfo for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineGetAgentSessionInfo function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, lineGetAgentSessionInfo


ITAgentSession::put_State

The put_State method sets the state of the agent session.

HRESULT put_State(
  AGENT_SESSION_STATE SessionState
);

Parameters

SessionState
[in] AGENT_SESSION_STATE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_INVALIDARG | The SessionState parameter is not a valid session state.
LINEERR_ | See lineSetAgentSessionState for error codes returned from this TAPI 2.1 function.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

This method wraps the TAPI 2.1 lineSetAgentSessionState function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSession, get_State, lineSetAgentSessionState, AGENT_SESSION_STATE


ITAgentSessionEvent

The ITAgentSessionEvent interface contains methods that retrieve the description of agent session events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_AGENTSESSION, the method's pEvent parameter is an IDispatch pointer for the ITAgentSessionEvent interface. The methods of this interface can be used to retrieve information concerning the agent session change that has occurred.

See About TAPI 3.0 Call Center Controls for additional information.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_AGENTSESSION event to enable reception of agent session events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAgentSessionEvent methods | Description
get_Session | Gets a pointer to the ITAgentSession interface.
get_Event | Gets an AGENT_SESSION_EVENT descriptor of the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITAgentSession, About TAPI 3.0 Call Center Controls, Register Events code snippet


ITAgentSessionEvent::get_Event

The get_Event method gets an AGENT_SESSION_EVENT descriptor of the event that occurred.

HRESULT get_Event(
  AGENT_SESSION_EVENT *pEvent
);

Parameters

pEvent
[out, retval] Pointer to the AGENT_SESSION_EVENT descriptor of the event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pEvent parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSessionEvent, AGENT_SESSION_EVENT


ITAgentSessionEvent::get_Session

The get_Session method gets a pointer to the ITAgentSession on which the event occurred.

HRESULT get_Session(
  ITAgentSession **ppSession
);

Parameters

ppSession
[out, retval] Pointer to the ITAgentSession interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppSession parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITAgentSessionEvent


ITQueue

Gets and sets information concerning a queue.

See About TAPI 3.0 Call Center Controls for additional information.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITQueue methods | Description
put_MeasurementPeriod | Sets period (in seconds) for which the switch and/or implementation stores and calculates information.
get_MeasurementPeriod | Gets period (in seconds) for which the switch and/or implementation stores and calculates information.
get_TotalCallsQueued | Gets total incoming calls for this queue during this measurement period.
get_CurrentCallsQueued | Gets number of incoming calls in queue.
get_TotalCallsAdandoned | Gets number of abandoned calls during this measurement period.
get_TotalCallsFlowedIn | Gets total calls that flowed into this queue (passed down from another queue or ACD group) during this measurement period.
get_TotalCallsFlowedOut | Gets total calls that flowed out this queue (passed down to another queue or ACD group) during this measurement period.
get_LongestEverWaitTime | Gets longest time any call waited in queue (in seconds).
get_CurrentLongestWaitTime | Gets longest time a currently waiting call has been in queue (in seconds).
get_AverageWaitTime | Gets average wait time (in seconds) for a call.
get_FinalDisposition | Gets total calls reaching the bottom of a call guide. Indicates a problem with queue design or response times.
get_Name | Gets queue name.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.


ITQueue::get_MeasurementPeriod

The get_MeasurementPeriod method gets the measurement period (in seconds) for which the switch and/or implementation stores and calculates information. For example, the get_TotalCallsQueued method returns the number of calls queued; get_MeasurementPeriod indicates if this value referenced the calls queued in an hour, a day, a month, etc.

HRESULT get_MeasurementPeriod(
  long *plPeriod
);

Parameters

plPeriod
[out, retval] Pointer to the measurement period

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plPeriod is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue, put_MeasurementPeriod


ITQueue::put_MeasurementPeriod

The put_MeasurementPeriod method sets the period (in seconds) for which the switch and/or implementation stores and calculates information.

HRESULT put_MeasurementPeriod(
  long lPeriod
);

Parameters

lPeriod
[in] Measurement period (in seconds).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | Value of lPeriod is zero.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.
LINEERR_ | See lineSetQueueMeasurementPeriod for error codes returned from this TAPI 2.1 function.

Remarks

The ITQueue::put_MeasurementPeriod method is a COM wrapper for the TAPI 2.1 lineSetQueueMeasurementPeriod function.

This method will accept negative values for the measurement period, but this will normally result in unreliable statistics.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue, get_MeasurementPeriod


ITQueue::get_TotalCallsQueued

The get_TotalCallsQueued method gets the total number of incoming calls for this queue during the current measurement period. The measurement period is switch or implementation specific. (See get_MeasurementPeriod.)

HRESULT get_TotalCallsQueued(
  long *plCalls
);

Parameters

plCalls
[out, retval] Pointer to the total number of incoming calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_CurrentCallsQueued

The get_CurrentCallsQueued method gets the number of incoming calls currently waiting.

HRESULT get_CurrentCallsQueued(
  long *plCalls
);

Parameters

plCalls
[out, retval] Pointer to the number of incoming calls in the queue.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_TotalCallsAbandoned

The get_TotalCallsAbandoned method gets the number of abandoned calls during the current measurement period. The measurement period is switch or implementation specific. (See get_MeasurementPeriod.)

HRESULT get_TotalCallsAbandoned(
  long *plCalls
);

Parameters

plCalls
[out, retval] Pointer to the number of calls abandoned.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_TotalCallsFlowedIn

The get_TotalCallsFlowedIn method gets the total number of calls that flowed into this queue (passed down from another queue or ACD group) during the current measurement period. The measurement period is switch or implementation specific. (See get_MeasurementPeriod.)

HRESULT get_TotalCallsFlowedIn(
  long *plCalls
);

Parameters

plCalls
[out, retval] Pointer to the number of calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_TotalCallsFlowedOut

The get_TotalCallsFlowedOut method gets the total number of calls that flowed out of this queue (passed down to another queue or ACD group) during the current measurement period. The measurement period is switch or implementation specific. (See get_MeasurementPeriod.)

HRESULT get_TotalCallsFlowedOut(
  long *plCalls
);

Parameters

plCalls
[out, retval] Pointer to number of calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_LongestEverWaitTime

The get_LongestEverWaitTime method gets the longest time any call waited in the queue (in seconds) during the current measurement period. The measurement period is switch or implementation specific. (See get_MeasurementPeriod.)

HRESULT get_LongestEverWaitTime(
  long *plWaitTime
);

Parameters

plWaitTime
[out, retval] Pointer to the wait time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plWaitTime is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_CurrentLongestWaitTime

The get_CurrentLongestWaitTime method gets the longest time a current call (still in the queue) has been waiting (in seconds) during the current measurement period. The measurement period is switch or implementation specific. (See get_MeasurementPeriod.).

HRESULT get_CurrentLongestWaitTime(
  long *plWaitTime
);

Parameters

plWaitTime
[out, retval] Pointer to wait time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plWaitTime is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_AverageWaitTime

The get_AverageWaitTime method gets the average time in the queue (in seconds) for a call during the current measurement period. The measurement period is switch or implementation specific. (See get_MeasurementPeriod.)

HRESULT get_AverageWaitTime(
  long *plWaitTime
);

Parameters

plWaitTime
[out, retval] Pointer to the average wait time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plWaitTime is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueue::get_FinalDisposition

The get_FinalDisposition method gets the total number of calls reaching the bottom of a call guide during the current measurement period. This indicates that a call has passed through an ACD system, moving from queue to queue, without being answered, which indicates a problem with the queue design or response times.

The measurement period is switch- or implementation-specific. (See get_MeasurementPeriod.)

HRESULT get_FinalDisposition(
  long *plCalls
);

Parameters

plCalls
[out, retval] Pointer to number of calls.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plCalls is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TIMEOUT | The operation failed because the TAPI 3.0 DLL timed it out. The timeout interval is two minutes.

Remarks

Measurement period for this information is switch and/or implementation specific (see get_MeasurementPeriod).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue. get_MeasurementPeriod


ITQueue::get_Name

The get_Name method gets the queue name.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out, retval] Pointer to BSTR representation of queue name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppName is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueue


ITQueueEvent

The ITQueueEvent interface contains methods that retrieve the description of Automatic Call Distribution (ACD) queue events. When the application's implementation of the ITTAPIEventNotification::Event method indicates a TAPI_EVENT equal to TE_QUEUE, the method's pEvent parameter is an IDispatch pointer for the ITQueueEvent interface. The methods of this interface can be used to retrieve information concerning a queue event that has occurred.

Note You must call the ITTAPI::put_EventFilter method and set an event filter mask that includes the TE_QUEUE event to enable reception of ACD queue events. If you do not call ITTAPI::put_EventFilter, your application will not receive any events. For more information, see the Events overview.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITQueueEvent methods | Description
get_Queue | Gets a pointer to the ITQueue interface.
get_Event | Gets the ACDQUEUE_EVENT descriptor of the event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTAPIEventNotification::Event, TAPI_EVENT, ITQueue, ACDQUEUE_EVENT, Register Events code snippet


ITQueueEvent::get_Event

The get_Event method gets the descriptor of the event that occurred.

HRESULT get_Event(
  ACDQUEUE_EVENT *pEvent
);

Parameters

pEvent
[out, retval] Pointer to ACDQUEUE_EVENT descriptor of event.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pEvent is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueueEvent, ACDQUEUE_EVENT


ITQueueEvent::get_Queue

The get_Queue method gets a pointer to the queue on which the event occurred.

HRESULT get_Queue(
  ITQueue **ppQueue
);

Parameters

ppQueue
[out, retval] Pointer to ITQueue interface on which event occurred.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppQueue is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITQueueEvent


Rendezvous IP Telephony Conferencing Overview

The TAPI 3.0 Rendezvous controls enable a programmer to create applications that can create and discover multimedia multicast IP conferences.

The key components of Rendezvous:

Directory Controls are an abstraction of conference listings on an ILS or NTDS server.

Conference Blob Controls represent conference-specific information such as start and stop time. Special interfaces are provided for SDP protocol blobs. For detailed information, see RFC 2327 entitled "SDP: Session Description Protocol." A current copy of this RFC can be located using an Internet search engine.

Multicast COM Interfaces are COM wrappers for the MADCAP functions, formerly know as MDHCP. These interfaces allow an application to get multicast addresses from a multicast address allocation server.

The following material provides a general overview and some usage examples of the Rendezvous controls for IP telephony and conferencing.


About Rendezvous IP Telephony Conferencing

The TAPI 3.0 Rendezvous controls provide mechanisms to advertise and discover multiparty multimedia IP conferences. The following describes a set of Component Object Model (COM) components and interfaces to implement conferencing.

COM is the basic coding model for TAPI 3.0, and familiarity with it is assumed throughout this document. For information on COM, search the Platform SDK.

Features

  • Provides the abstraction of a conference directory for manipulating announcements of multimedia conferences
  • Provides security through authentication, encryption, and a per-announcement access control layer (ACL)
  • Provides a common schema for a conference announcement, enabling searches by attribute values
  • Allows extensions through a provider-maintained attribute (conference blob) in the schema
  • Provides a COM wrapper for the multicast address allocation (MADCAP) API

Architecture

The following descriptions and diagram illustrate key aspects of the system architecture.

  • The client can manipulate conferences stored on an ILS dynamic directory or NTDS server using Rendezvous controls. The Lightweight Directory Access Protocol (LDAP) is used to communicate with an ILS server.
  • The Rendezvous controls provide dual COM interfaces for scripting and programming.
  • A Session Announcement Protocol (SAP) server with direct access to the Internet listens to conference announcements on the Internet and populates ILS dynamic servers with the conference information. Similarly, it also announces the locally created conferences whose scope includes the Internet. (The SAP server is not planned for Windows® 2000.)


Using Rendezvous IP Telephony Conferencing

Rendezvous consists of three basic sets of interfaces:

  • Directory controls provide a means of discovering, creating, or modifying the conference and user information on an ILS or NTDS server.
  • Conference blob controls allow provider-specific modifications to a conference.
  • Multicast COM interfaces provide a means of reserving addresses for use by multicast conferences.


Directory Controls

The following diagram illustrates the main objects involved in TAPI 3.0 Rendezvous directory controls. Interfaces shown are hyperlinked into the relevant reference pages.

The main directory control interface is ITRendezvous, which must be created by calling CoCreateInstance. The Rendezvous object exposes methods to get lists of available directories and to create new directories or directory objects.

A directory resides on a server and is a list of directory objects along with descriptive information. Methods associated with ITDirectory can get information associated with the directory as a whole, such as whether it is an ILS directory.

A directory object can represent a conference or a user. The ITDirectoryObject interface supplies methods that can retrieve or modify information generic to a directory object, such as the dialable address.

Conference and user information, such as the URL of a conference or the primary IP phone of a user, is manipulated by methods provided in the ITDirectoryObjectConference and ITDirectoryObjectUser interfaces.


Conference Blob Controls

The following diagram illustrates the main objects involved in TAPI 3.0 conference blob controls. Interfaces shown are hyperlinked into the relevant reference pages.

The conference blob contains provider-specific information on a conference object. A pointer to the ITConferenceBlob interface blob is obtained by doing a QueryInterface on ITDirectoryObjectConference. The ITConferenceBlob interface provides methods for basic manipulation of a generic conference blob. An application using non-SDP conference blobs must implement its own methods for detail manipulation.

Rendezvous provides the ITSdp interface for manipulating SDP conference blobs. The SDP is a protocol for describing multimedia sessions and their related scheduling information. For additional information on the SDP protocol, locate Internet Engineering Task Force (IETF) RFC 2327 entitled "SDP: Session Description Protocol." If the ITSDP interface exists for a given conference blob, you can obtain a pointer to it by doing a QueryInterface on ITConferenceBlob.

For SDP conference blobs, the ITTimeCollection, ITTime, ITMediaCollection, and ITMedia interfaces allow detailed control of SDP conference time and media characteristics.


Multicast COM Interfaces

The multicast COM interfaces allow access to the network's facility for allocating, renewing, and releasing leases on multicast addresses. They encapsulate a set of Win32 functions and data structure definitions. The COM interfaces free the programmer from the burden of understanding and manipulating these data structures. Moreover, because TAPI 3.0 itself is COM-based, these interfaces make multicast address allocation accessible in a way that is consistent with the other facilities provided by TAPI 3.0. Applications written using Visual Basic®, Java, or scripting languages that cannot normally access the Win32 API directly are able to use these interfaces.

Multicast address allocation is currently the subject of an IETF working group. To access current information, query on "MDHCP" or "MADCAP" and "Internet draft" using any Internet search engine. In addition to MADCAP, the proposed architecture includes a protocol for server-to-server coordination within a domain or AS, as well as a protocol for interdomain coordination. While this architecture is currently evolving, the client need not concern itself with the details of this scheme.

This component currently supports only IP version 4 addresses.

Note The protocol used for these interfaces is currently named MADCAP. In previous versions it was known as MDHCP.

The multicast object is created by calling CoCreateInstance on the IMcastAddressAllocation interface. The IMcastAddressAllocation interface exposes the EnumerateScopes method, which allows an application to get a list of all available multicast scopes.

Once a working scope has been obtained, the RequestAddress method is used to request a multicast address from the server. If the request is successful, an IMcastLeaseInfo pointer is returned. The EnumerateAddresses method exposed by this interface can then be used to obtain the addresses.

Each Media object associated with the conference exposes an ITConnection interface. The ITConnection::SetAddressInfo method allows assignment of the multicast addresses obtained to the media of the conference. The address must be set for each ITConnection interface of every Media object associated with the conference.


Rendezvous Code Snippets

The following code snippets illustrate some basic Rendezvous operations. For a full code example, please check the Platform SDK Code Samples under NetDS/TAPI. The TAPI3 directory contains a sample entitled "Rend".

These snippets do not have error checking or proper COM reference adds and releases.


Connecting to an ILS Server

The following code fragment illustrates establishing a connection to a known ILS server.

// Create the Rendezvous component.
ITRendezvous *pRend;
CoCreateInstance(
        CLSID_Rendezvous,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_ITRendezvous,
        (void **)&pRend
        );

// Set the ILS server name.
BSTR bName = SysAllocString( wstrServerName );

// Create the directory component.
ITDirectory *pDirectory;
hr = pRend->CreateDirectory(
        DT_ILS,
        bName,
        &pDirectory
        );

// Connect to the server.
hr = pDirectory->Connect(FALSE);

See Also

ITRendezvous, ITDirectory


Enumerating Conference Directories

The following code fragment illustrates the enumeration of conferences on a specified ILS server. This fragment assumes that connecting to an ILS server has already been performed.

// Enumerate the available directory objects.
IEnumDirectoryObject *pEnumDirectoryObject;
BSTR bNameToSearch = SysAllocString( L"*" );
hr = pDirectory->EnumerateDirectoryObjects(
        OT_CONFERENCE,
        bNameToSearch,
        &pEnumDirectoryObject
        );

for (;;)
{
    if ((hr = pEnumDirectoryObject->Next(
                       1,
                       &pDirectoryObject,
                       NULL )
         ) != S_OK )
    {
        break;
    }
    // Perform the desired operation on the directory object.
}

SysFreeString( bNameToSearch );

See Also

IEnumDirectoryObject


Creating a Conference Announcement

The following code fragment illustrates the creation of a simple conference announcement. This fragment assumes that connecting to an ILS server has already been performed.

// Create the new directory object.
ITDirectoryObject *pDirectoryObject;
hr = pRend->CreateDirectoryObject(
        OT_CONFERENCE,
        bName,
        &pDirectoryObject
        );

// Modify the settings if necessary.
// See the next topic for modification of a simple conference
// and "Acquiring a Multicast Address" for multicast operations.

// Add the new directory object to the directory.
hr = pDirectory->AddDirectoryObject(pDirectoryObject);

See Also

ITDirectoryObject, Modifying a Known Conference, Acquiring a Multicast Address


Modifying a Known Conference

The following code fragment illustrates modification of a conference's time span. The default time span is thirty minutes. In this fragment, the time span is set to one year.

This fragment assumes that connecting to an ILS server has already been performed and that a conference directory enumeration has been performed to obtain the directory entry that will be modified.

This fragment also assumes this is not a multicast conference. Changing the times on a multicast conference requires notification of the multicast address allocation server. See Acquiring a Multicast Address for an example of working with multicast addressing.

// Obtain the conference configuration interface.
ITDirectoryObjectConference *pConference;

hr = pDirectoryObject->QueryInterface(
        IID_ITDirectoryObjectConference,
        (void **)&pConference
        );

double vStartTime, vStopTime;
hr = pConference->get_StartTime( &vStartTime );

SYSTEMTIME time;
memset( &time, 0, sizeof( SYSTEMTIME ) );
VariantTimeToSystemTime( vStartTime, &time );
time.wYear++;
SystemTimeToVariantTime( time, &vStopTime );

hr = pConference->put_StopTime( vStopTime );

See Also

ITDirectoryObjectConference


Adding a User Object to an ILS Server

The following code fragment illustrates publishing a user object in an ILS server. Once a user object is published, remote parties can use the user object to make calls to the specified user.

This fragment assumes that connecting to an ILS server has already been performed.

// Automatically refresh user objects in the background so that they do not time out.
hr = pDirectory->EnableAutoRefresh(VARIANT_TRUE);

// Create a user object.
BSTR bUserName = SysAllocString(L"myname");
ITDirectoryObject * pDirectoryObject;
hr = pRend->CreateDirectoryObject(
        OT_USER,
        bUserName,
        &pDirectoryObject
        );
SysFreeString(bUserName);

// Get the user configuration interface.
ITDirectoryObjectUser * pUser;
hr = pDirectoryObject->QueryInterface(
        IID_ITDirectoryObjectUser,
        (void **) &pUser
        );

// Set the IP "phone number" of this user.
BSTR bHostName = SysAllocString(L"mymachine.microsoft.com");
hr = pUser->put_IPPhonePrimary(bHostName);
SysFreeString(bHostName);

// Copy the user object to the server.
hr = pDirectory->AddDirectObject(pDirectoryObject);

See Also

ITDirectory, ITDirectoryObject, ITDirectoryObjectUser


Acquiring a Multicast Address

The following code fragment illustrates how to request and set a multicast address for a conference.

For the sake of simplicity, this fragment shows the assignment of one multicast address to one media item. In actuality, the selection of a scope, the multicast address request, and the assignment will be performed for every media item involved in the conference.

This fragment assumes that connecting to an ILS server has already been performed. The operations shown here would be performed in the "Modify the settings if necessary" section of Creating a Conference Announcement.

// Get the Conference blob interface pointer
// from the Directory object.
ITConferenceBlob * pConBlob;
hr = pDirectoryObject->QueryInterface(
        IID_ITConferenceBlob,
        (void **) &pConBlob
        );

// Get the SDP blob interface pointer
// from conference blob.
ITSdp * pSdp;
hr = pConBlob->QueryInterface(
        IID_ITSdp,
        (void **) &pSdp
        );

// Get the media collection associated with
// the SDP blob, and a count of the media.
ITMediaCollection *pMC;
hr = pSdp->get_MediaCollection(&pMC)
long lMCCount = 0;
pMC->get_Count( &lMCCount );

// Create the multicast object.
IMcastAddressAllocation *pIMcastAddressAllocation;
HRESULT hr = CoCreateInstance(
        CLSID_IMcastAddressAllocation,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IMcastAddressAllocation,
        (void **) &pIMcastAddressAllocation
        );

// Get an enumeration of
// multicast scopes available.
IEnumMcastScope *pEnum = NULL;
hr = pIMcastAddressAllocation->EnumerateScopes(&pEnum)) )

// Select a multicast scope.
IMcastScope *pScope;
hr = pEnum->Next(1, &pScope, NULL)

// Request an address.
// If successful, return the lease information.
DATE dateStart, dateStop;
SystemTimeToVariantTime( pStart, &dateStart );
SystemTimeToVariantTime( pStop, &dateStop );
IMcastLeaseInfo *pInfo;
hr = pIMcastAddressAllocation->RequestAddress(
        pScope,
        dateStart,
        dateStop,
        1,
        &pInfo
        );

//
unsigned char nTTL = 15;
long lTemp;
hr = pInfo->get_TTL(&lTemp)
nTTL = (unsigned char) nTTL;

// Get a multicast address.
IEnumBstr *pEnumAddr = NULL;
hr = pInfo->EnumerateAddresses(
        &pEnumAddr)
BSTR bstrAddress = NULL;
hr = pEnumAddr->Next(1, &bstrAddress, NULL);

// Set the address using the ITConnection interface
// on the Media object.
ITMedia *pMedia;
hr = pMC->get_Item( 0, &pMedia);
ITConnection *pITConn;
hr = pMedia->QueryInterface(
        IID_ITConnection,
        (void **) &pITConn
        );
hr = pITConn->SetAddressInfo(
        bstrAddress,
        1,
        nTTL
        );

See Also

Multicast COM Interfaces, IMcastAddressAllocation, IMcastScope, IMcastLeaseInfo, IEnumMcastScope, ITConferenceBlob, ITSdp, ITMediaCollection, IEnumBstr, ITMedia, ITConnection


Rendezvous IP Telephony Conferencing Reference

TAPI 3.0's Rendezvous API is a group of Component Object Model (COM) interfaces that can be used to advertise and discover multiparty multimedia conferences. The following material provides details on the objects, interfaces, and methods provided.

You may also wish to search the Platform SDK for information on DirectShow™ and COM. TAPI 3.0 uses DirectShow filters and filter managers to control the media stream following connection setup. COM is the basic coding model for TAPI 3.0, and familiarity with it is assumed throughout this document.

In addition, the Code Samples section of the Platform SDK contains a sample entitled "Rend" under NetDS/TAPI/TAPI3.

Rendezvous COM Interfaces

Rendezvous Enumerations

Rendezvous Constants

See Also

IP Conference MSP


Rendezvous COM Interfaces

The following table lists COM objects and interfaces associated with the Rendezvous conferencing controls.

For additional information on the Component Object Model (COM), please refer to the relevant sections in the Platform SDK.

Interfaces | Description
IEnumDialableAddrs | Enumerates the dialable addresses available in the current directory.
IEnumDirectory | Enumerates ITDirectory objects.
IEnumDirectoryObject | Enumerates ITDirectoryObject objects.
IEnumMcastScope | Enumerates IMcastScope objects.
IEnumMedia | Enumerates ITMedia objects.
IEnumTime | Enumerates ITTime objects.
IMcastAddressAllocation | Main interface for COM wrapper of multicast address allocation.
IMcastLeaseInfo | Provides methods to retrieve and set address lease information.
IMcastScope | Encapsulates all the properties of a multicast scope and provides methods to get information about the scope.
ITAttributeList | Allows getting and setting of uninterpreted attributes.
ITConferenceBlob | Provides access to provider-specific conference information.
ITConnection | Provides methods to manipulate connection factors such as conference address, scope, and bandwidth.
ITDirectory | Gets and sets directory information, and provides access to a particular directory object.
ITDirectoryObject | Gets and sets generic information for a conference or user within a directory.
ITDirectoryObjectConference | Gets and sets generic information specific to a conference, such as start and stop times.
ITDirectoryObjectUser | Gets and sets generic information specific to a user, such as the name of a computer that is the user's primary IP phone.
ITILSConfig | Gets and sets information specific to the server of a given ILS directory.
ITMedia | Gets and sets basic media properties such as the media name and transport protocol.
ITMediaCollection | Allows media access by index. Enables creation and deletion of media.
ITRendezvous | Main interface for the Rendezvous control.
ITSdp | Manipulates the SDP (Session Description Protocol) blob. Reference: RFC 2327.
ITTime | Provides access to a set of activation times for the session.
ITTimeCollection | Allows time-component access by index. Enables creation and deletion of time components.


IEnumDialableAddrs

The IEnumDialableAddrs interface provides COM-standard enumeration methods to discover and use the available dialable addresses in a directory. The ITDirectoryObject::EnumerateDialableAddrs method returns a pointer to this interface.

Methods in Vtable Order

IUnknown Methods

IEnumDialableAddrs methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


IEnumDialableAddrs::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  BSTR *ppElements,
  ULONG *pcFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out] Pointer to a BSTR representation of the address list.
pcFetched
[out] Pointer to the number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.

Remarks

The application must use SysFreeString to free the memory allocated for the ppElements parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDialableAddrs


IEnumDialableAddrs::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDialableAddrs


IEnumDialableAddrs::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDialableAddrs


IEnumDialableAddrs::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumDialableAddrs **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to the new IEnumDialableAddrs object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDialableAddrs


IEnumDirectory

The IEnumDirectory interface provides COM-standard enumeration methods for the ITDirectory interface. The ITRendezvous::EnumerateDefaultDirectories method returns a pointer to IEnumDirectory.

Methods in Vtable Order

IUnknown Methods

IEnumDirectory methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


IEnumDirectory::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITDirectory **ppElements,
  ULONG *pcFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to the ITDirectory interface.
pcFetched
[out] Pointer to the number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectory


IEnumDirectory::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectory


IEnumDirectory::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectory


IEnumDirectory::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumDirectory **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to the new IEnumDirectory object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectory


IEnumDirectoryObject

The IEnumDirectoryObject interface provides COM-standard enumeration methods for the ITDirectoryObject interface. The ITDirectory::EnumerateDirectoryObjects method returns a pointer to IEnumDirectoryObject.

Methods in Vtable Order

IUnknown Methods

IEnumDirectoryObject methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


IEnumDirectoryObject::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITDirectoryObject **pVal,
  ULONG *pcFetched
);

Parameters

celt
[in] Number of elements requested.
pVal
[out] Pointer to the ITDirectoryObject interface.
pcFetched
[out] Pointer to the number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The pVal parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectoryObject


IEnumDirectoryObject::Reset

The Reset method resets to the beginning of enumeration sequence.

HRESULT Reset();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectoryObject


IEnumDirectoryObject::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectoryObject


IEnumDirectoryObject::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumDirectoryObject **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to the new IEnumDirectoryObject object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

IEnumDirectoryObject


IEnumMcastScope

The IEnumMcastScope interface provides COM-standard enumeration methods for the IMcastScope interface. The IMcastAddressAllocation::EnumerateScopes method returns a pointer to IEnumMcastScope.

Methods in Vtable Order

IUnknown Methods

IEnumMcastScopes methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.


IEnumMcastScope::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumMcastScope **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to the new IEnumMcastScope object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IEnumMcastScope


IEnumMcastScope::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  IMcastScope **ppScopes,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppScopes
[out] Pointer to the IMcastScope interface.
pceltFetched
[out] Pointer to the number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppScopes parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IEnumMcastScope


IEnumMcastScope::Reset

The Reset method resets to the beginning of enumeration sequence.

HRESULT Reset();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IEnumMcastScope


IEnumMcastScope::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IEnumMcastScope


IEnumMedia

The IEnumMedia interface provides COM-standard enumeration methods for the ITMedia interface. The ITMediaCollection::get_EnumerationIf method returns a pointer to IEnumMedia.

Methods in Vtable Order

IUnknown Methods

IEnumMedia methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


IEnumMedia::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITMedia **pVal,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
pVal
[out] Pointer to the ITMedia interface.
pceltFetched
[out] Pointer to the number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The pVal parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumMedia


IEnumMedia::Reset

The Reset method resets to the beginning of enumeration sequence.

HRESULT Reset();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumMedia


IEnumMedia::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumMedia


IEnumMedia::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumMedia **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to the new IEnumMedia object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumMedia


IEnumTime

The IEnumTime interface provides COM-standard enumeration methods for the ITTime interface. The ITTimeCollection::get_EnumerationIf method returns a pointer to IEnumTime.

Methods in Vtable Order

IUnknown Methods

IEnumTime methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to the beginning of the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


IEnumTime::Next

The Next method gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITTime **pVal,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
pVal
[out] Pointer to the ITTime interface.
pceltFetched
[out] Pointer to the number of elements actually supplied. May be NULL if celt is 1.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The pVal parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumTime


IEnumTime::Reset

The Reset method resets to the beginning of the enumeration sequence.

HRESULT Reset();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumTime


IEnumTime::Skip

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumTime


IEnumTime::Clone

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumTime **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to the new IEnumTime object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

IEnumTime


IMcastAddressAllocation

IMcastAddressAllocation is the main interface for multicast address allocation. An application calls the COM CoCreateInstance function on this interface to create the multicast client interface object.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

IMcastAddressAllocation methods | Description
get_Scopes | Gets a VARIANT collection of IMcastScope pointers.
EnumerateScopes | Creates an enumeration of multicast scopes interfaces available.
RequestAddress | Obtains a new lease for one or more multicast addresses.
RenewAddress | Renews an address lease.
ReleaseAddress | Releases a lease that was obtained previously.
CreateLeaseInfo | Creates a lease information object.
CreateLeaseInfoFromVariant | Creates a lease information object. Similar to CreateLeaseInfo, but used by Automation client languages such as Visual Basic.

Remarks

The multicast COM interfaces allow access to the network's facility for allocating, renewing, and releasing leases on multicast addresses. They encapsulate a set of Win32 functions and data structure definitions. The COM interfaces free the programmer from the burden of understanding and manipulating these data structures. Moreover, because TAPI 3.0 itself is COM-based, these interfaces make multicast address allocation accessible in a way that is consistent with the other facilities provided by TAPI 3.0. Applications written using Visual Basic®, Java, or scripting languages must use these COM interfaces—they cannot normally access the Win32 API directly.

In addition, this component provides seamless and transparent support for local address allocation for non-multicast environments. The DWORD registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\MCAST\LocalAllocation, when set to a nonzero value, specifies that random number generation performed on the local machine is to be used for the allocation of all multicast addresses. This allows applications to function the same way on a network without a multicast address allocation server as they would on a network with a multicast address allocation server. If the registry value is set to zero or does not exist, this component performs normally as described in the rest of this specification. Note that local address allocation is never used unless this registry key is set to a nonzero value; local address allocation is not a fallback mechanism for a temporarily inaccessible multicast address allocation server.

Multicast address allocation is currently the subject of an IETF working group. To access current information, query on "Internet draft" and "MDHCP" or "MADCAP" using any Internet search engine. In addition to MADCAP (previously called MDHCP), the proposed architecture includes a protocol for server-to-server coordination within a domain or AS, as well as a protocol for interdomain coordination. While this architecture is currently evolving, the client need not concern itself with the details of this scheme.

This component currently supports only IP version 4 addresses.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, IMcastScope


IMcastAddressAllocation::CreateLeaseInfo

The CreateLeaseInfo method creates a lease information object for a subsequent call to RenewAddress or ReleaseAddress.

HRESULT CreateLeaseInfo(
  DATE LeaseStartTime,
  DATE LeaseStopTime,
  DWORD dwNumAddresses,
  LPWSTR *ppAddresses,
  LPWSTR pRequestID,
  LPWSTR pServerAddress,
  IMcastLeaseInfo **ppReleaseRequest
);

Parameters

LeaseStartTime
[in] The start time of the lease.
LeaseStopTime
[in] The stop time of the lease.
dwNumAddresses
[in] The number of addresses associated with the lease.
ppAddresses
[in] An array of LPWSTR pointers of size dwNumAddresses. Each LPWSTR is an IP version 4 address in dotted quad notation (for example, 10.111.222.111).
pRequestID
[in] An LPWSTR specifying the request ID for the original request. This is obtained by calling IMcastLeaseInfo::get_RequestID on the lease information object corresponding to the original request. The request ID should be saved in persistent storage between executions of the application program. If you are renewing or releasing a lease that was requested during the same run of the application, you have no reason to use CreateLeaseInfo; just pass the existing IMcastLeaseInfo pointer to RenewAddress or ReleaseAddress.
pServerAddress
[in] Specifies server address.
ppReleaseRequest
[out, retval] Pointer to the IMcastLeaseInfo interface created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory exists to create the required objects.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation


IMcastAddressAllocation::CreateLeaseInfoFromVariant

The CreateLeaseInfoFromVariant method creates a lease information object for a subsequent call to RenewAddress or ReleaseAddress. This method is similar to CreateLeaseInfo but is used by Automation client languages such as Visual Basic.

HRESULT CreateLeaseInfoFromVariant(
  DATE LeaseStartTime,
  DATE LeaseStopTime,
  VARIANT vAddresses,
  BSTR pRequestID,
  BSTR pServerAddress,
  IMcastLeaseInfo **ppReleaseRequest
);

Parameters

LeaseStartTime
[in] The start time of the lease.
LeaseStopTime
[in] The stop time of the lease.
vAddresses
[in] A VARIANT containing a SAFEARRAY of BSTR strings. Each BSTR is an IP version 4 address in dotted quad notation (for example, 10.111.222.111).
pRequestID
[in] Pointer to a BSTR specifying the request ID for the original request. This is obtained by calling IMcastLeaseInfo::get_RequestID on the lease information object corresponding to the original request. The request ID should be saved in persistent storage between executions of the application program. If you are renewing or releasing a lease that was requested during the same run of the application, you have no reason to use CreateLeaseInfo; just pass the existing IMcastLeaseInfo pointer to RenewAddress or ReleaseAddress.
pServerAddress
[in] Pointer to a BSTR specifying the server address.
ppReleaseRequest
[out, retval] Pointer to the IMcastLeaseInfo interface created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory exists to create the required objects.

Remarks

The application must use SysAllocString to allocate memory for the pRequestID and pServerAddress parameters. The application must use SysFreeString to free the memory when the variables are no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation, IMcastLeaseInfo


IMcastAddressAllocation::EnumerateScopes

The EnumerateScopes method creates an enumeration of multicast scopes available. This method is primarily for C++ programmers. Visual Basic and other scripting languages use get_Scopes instead.

HRESULT EnumerateScopes(
  IEnumMcastScope **ppEnumMcastScope
);

Parameters

ppEnumMcastScope
[out] Returns a pointer to a new IEnumMcastScope object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_FAIL | There are no scopes available.
E_OUTOFMEMORY | Not enough memory exists to create the required objects.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation


IMcastAddressAllocation::ReleaseAddress

The ReleaseAddress method releases a lease that was obtained previously.

HRESULT ReleaseAddress(
  IMcastLeaseInfo *pReleaseRequest
);

Parameters

pReleaseRequest
[in] Pointer to the lease information interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory exists to make the request.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation


IMcastAddressAllocation::RenewAddress

The RenewAddress method renews an address lease. Call CreateLeaseInfo to specify the parameters of the renewal request, and then call this method to make the request.

HRESULT RenewAddress(
  long lReserved,
  IMcastLeaseInfo *pRenewRequest,
  IMcastLeaseInfo **ppRenewResponse
);

Parameters

lReserved
[in] Reserved parameter. An application should pass in a value of 0.
pRenewRequest
[in] Pointer to an IMcastLeaseInfo object specifying the attributes of the requested renewal, such as which address(es) to renew. This is obtained by calling CreateLeaseInfo.
ppRenewResponse
[out] Pointer to an interface pointer that will be set to point to a new IMcastLeaseInfo object. This interface can then be used to discover the attributes of the renewed lease. See IMcastScope for more information.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_INVALIDARG | Requested stop time is prior to the requested stop time.
E_OUTOFMEMORY | Not enough memory to create the required objects.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation


IMcastAddressAllocation::RequestAddress

The RequestAddress method obtains a new lease for one or more multicast addresses. The EnumerateScopes or get_Scopes method must be called first.

HRESULT RequestAddress(
  IMcastScope * pScope,
  DATE LeaseStartTime,
  DATE LeaseStopTime,
  long NumAddresses,
  IMcastLeaseInfo **ppLeaseResponse
);

Parameters

pScope
[in] Identifies the multicast scope from which the application needs an address. The application first calls get_Scopes or EnumerateScopes to obtain a list of available scopes.
LeaseStartTime
[in] Requested time for the lease on these addresses to start. The start time that is actually granted may be different.
LeaseStopTime
[in] Requested time for the lease on these addresses to stop. The stop time that is actually granted may be different.
NumAddresses
[in] The number of addresses requested. Fewer addresses may actually be granted.
ppLeaseResponse
[out] Pointer to an interface pointer that will be set to point to a new IMcastLeaseInfo object. This interface can then be used to discover the actual attributes of the granted lease. See IMcastScope for more information.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory exists to create the required objects.
E_INVALIDARG | Requested stop time is prior to requested stop time.

Remarks

Although these COM interfaces and their implementation support allocation of multiple addresses at a time, multiple allocation is not currently supported by the underlying Win32 calls. You may need to use a loop for multiple address allocation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation


IMcastAddressAllocation::get_Scopes

The get_Scopes method creates a collection of IMcast scopes available. This method is similar to EnumerateScopes, but is used by scripting languages such as Visual Basic.

HRESULT get_Scopes(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to a VARIANT receiving an ITCollection of IMcastScope interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_FAIL | There are no scopes available.
E_OUTOFMEMORY | Not enough memory exists to create the required objects.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation, ITCollection, IMcastScope


IMcastLeaseInfo

The IMcastLeaseInfo interface exposes methods that can get or set information concerning a multicast address allocation. The IMcastLease object is created by calling IMcastAddressAllocation::CreateLeaseInfo.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

IMcastLeaseInfo methods | Description
get_RequestID | Obtains the request identifier of the lease.
get_LeaseStartTime | Obtains the start time of the lease.
put_LeaseStartTime | Sets the start time of the lease.
get_LeaseStopTime | Obtains the stop time of the lease.
put_LeaseStopTime | Sets the stop time of the lease.
get_AddressCount | Obtains the number of addresses requested or granted in this lease.
get_ServerAddress | Obtains a string representing the address of the multicast server granting this lease.
get_TTL | Obtains the TTL (time to live) value associated with this lease.
get_Addresses | Obtains the collection of multicast addresses that are the subject of this lease or lease request. Similar to EnumerateAddresses, but used by scripting languages.
EnumerateAddresses | Obtains the collection of multicast addresses that are the subject of this lease or lease request.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastAddressAllocation, IMcastScope, IMcastAddressAllocation::CreateLeaseInfo, IMcastAddressAllocation::RequestAddress, IMcastAddressAllocation::RenewAddress


IMcastLeaseInfo::EnumerateAddresses

The EnumerateAddresses method obtains the collection of multicast addresses that are the subject of this lease or lease request. This method is primarily for C++ programmers. Visual Basic and other scripting languages use get_Addresses instead.

HRESULT EnumerateAddresses(
  IEnumBstr **ppEnumAddresses
);

Parameters

ppEnumAddresses
[out, retval] Returns a pointer to a new IEnumBstr object. IEnumBstr is a standard enumerator interface that enumerates BSTR strings. Each string is an IP version 4 address in dotted quad notation (for example, 10.111.222.111).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory to allocate the enumerator.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, IEnumBstr, get_Addresses


IMcastLeaseInfo::get_AddressCount

The get_AddressCount method obtains the number of addresses requested or granted in this lease.

HRESULT get_AddressCount(
  long *pCount
);

Parameters

pCount
[out] Pointer to a LONG that will receive the number of addresses requested or granted in this lease.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo


IMcastLeaseInfo::get_Addresses

The get_Addresses method obtains the collection of multicast addresses that are the subject of this lease or lease request. This method is primarily for Visual Basic and other scripting languages; C++ programmers use EnumerateAddresses instead.

HRESULT get_Addresses(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to a VARIANT receiving an ITCollection of ITAddress interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory to allocate the collection.

Remarks

Each address is an IP version 4 address represented as a BSTR in dotted quad notation (for example, 10.111.222.111).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, EnumerateAddresses


IMcastLeaseInfo::get_LeaseStartTime

The get_LeaseStartTime method obtains the start time of the lease.

HRESULT get_LeaseStartTime(
  DATE *pTime
);

Parameters

pTime
[out] Pointer to a DATE that will receive the start time of the lease.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_INVALIDARG | Format conversion failed for the start time or stop time.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, IMcastLeaseInfo::put_LeaseStartTime


IMcastLeaseInfo::get_LeaseStopTime

The get_LeaseStopTime method obtains the stop time of the lease.

HRESULT get_LeaseStopTime(
  DATE *pTime
);

Parameters

pTime
[out] Pointer to a DATE that will receive the stop time of the lease.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_INVALIDARG | Format conversion failed for the start time or stop time.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, put_LeaseStopTime


IMcastLeaseInfo::get_RequestID

The get_RequestID method obtains the request ID for a lease. The primary purpose of this method is to allow you to save the request ID after your application exits, so that you can call IMcastAddressAllocation::CreateLeaseInfo to re-create the lease information object during a subsequent run. This allows you to renew or release a lease after the instance of your program that originally requested the lease has exited.

HRESULT get_RequestID(
  BSTR *ppRequestID
);

Parameters

ppRequestID
[out] Pointer to a BSTR that will receive the request ID for this lease. The request ID uniquely identifies this lease request to the server.

Return Values

Value | Meaning
S_OK | Method succeeded.
S_FAIL | The lease information object contains an invalid request ID.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory to allocate the BSTR.

Remarks

The application must use SysFreeString to free the memory allocated for the ppRequestID parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo


IMcastLeaseInfo::get_ServerAddress

The get_ServerAddress method obtains a string representing the address of the multicast server granting this lease.

HRESULT get_ServerAddress(
  BSTR *ppAddress
);

Parameters

ppAddress
[out] Pointer to a BSTR that will receive a string representation of the address of the server granting this request or renewal.

Return Values

Value | Meaning
S_OK | Method succeeded.
S_FALSE | Server address unspecified.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory exists to allocate the string.

Remarks

The BSTR string ppAddress is an IP version 4 address in dotted quad notation (for example, 10.111.222.111). If a lease information object does not describe a granted lease (for example, it was not returned by IMcastAddressAllocation::RequestAddress or IMcastAddressAllocation::RenewAddress), the address is reported as the string "Unspecified".

The application must use SysFreeString to free the memory allocated for the ppAddress parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo


IMcastLeaseInfo::get_TTL

The get_TTL method obtains the time to live (TTL) value associated with this lease.

HRESULT get_TTL(
  long *pTTL
);

Parameters

pTTL
[out] Pointer to a LONG that will receive the TTL value associated with this lease.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_FAIL | There is no TTL associated with this lease.

Remarks

The TTL is more or less significant in the implementation of multicast routing. Generally, the higher the TTL value, the "larger" or more inclusive the multicast scope. Most applications need not address the TTL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo


IMcastLeaseInfo::put_LeaseStartTime

The put_LeaseStartTime method sets the start time of the lease. This method, along with put_LeaseStopTime, allows renewal of a lease without calling IMcastAddressAllocation::CreateLeaseInfo.

HRESULT put_LeaseStartTime(
  DATE time
);

Parameters

time
[in] A DATE specifying the start time of the lease.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | Format conversion failed for the start time or stop time.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, get_LeaseStartTime


IMcastLeaseInfo::put_LeaseStopTime

The put_LeaseStopTime method sets the stop time of the lease. This method, along with put_LeaseStartTime, allows you to renew a lease without calling IMcastAddressAllocation::CreateLeaseInfo.

HRESULT put_LeaseStopTime(
  DATE time
);

Parameters

time
[in] A DATE specifying the stop time of the lease.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | Format conversion failed for the start time or stop time.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, get_LeaseStopTime


IMcastScope

The IMcastScope interface is obtained by calling IMcastAddressAllocation::EnumerateScopes or IMcastAddressAllocation::get_Scopes. It encapsulates all the properties of a multicast scope and provides methods to get information about the scope. This is a "read-only" interface in that it has "get" methods but no "put" methods.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

IMcastScope methods | Description
get_ScopeID | Obtains the scope ID associated with this scope
get_ServerID | Obtains the server ID associated with this scope.
get_InterfaceID | Obtains the interface ID associated with this scope.
get_ScopeDescription | Obtains a textual description associated with this scope.
get_TTL | Obtains time to live information for the multicast server.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastLeaseInfo, IMcastScope


IMcastScope::get_ScopeDescription

The get_ScopeDescription method obtains a textual description associated with this scope. The description is used only for clarifying the purpose or meaning of a scope and is not needed for any subsequent calls.

HRESULT get_ScopeDescription(
  BSTR *ppDescription
);

Parameters

ppDescription
[out] Pointer to a BSTR that will receive a description of this scope. The description was established when this scope was configured on the multicast server.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.
E_OUTOFMEMORY | Not enough memory exists to allocate the string.

Remarks

The application must use SysFreeString to free the memory allocated for the ppDescription parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastScope


IMcastScope::get_ScopeID

The get_ScopeID method obtains an identifier for the scope of multicast addresses. The scope ID and server ID are needed to select this scope in subsequent calls to IMcastAddressAllocation::RequestAddress, IMcastAddressAllocation::RenewAddress, or IMcastAddressAllocation::ReleaseAddress.

HRESULT get_ScopeID(
  long *pID
);

Parameters

pID
[out] Pointer to a LONG that will receive the scope ID of this scope, which is the ID that was assigned to this scope when it was configured on the multicast server.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastScope, IMcastScope::get_ServerID


IMcastScope::get_ServerID

The get_ServerID method obtains the server ID associated with this scope. The scope ID and server ID are needed to select this scope in subsequent calls to IMcastAddressAllocation::RequestAddress, IMcastAddressAllocation::RenewAddress, or IMcastAddressAllocation::ReleaseAddress.

HRESULT get_ServerID(
  long *pID
);

Parameters

pID
[out] Pointer to a LONG that will receive the server ID of this scope, which is the ID that was assigned to the multicast address allocation server that published this scope at the time that the server was configured.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastScope, IMcastScope::get_ScopeID


IMcastScope::get_TTL

The get_TTL method obtains the time to live value for the multicast scope.

HRESULT get_TTL(
  long *pTTL
);

Parameters

pTTL
[out] Pointer to a time to live value for multicast scope.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastScope


IMcastScope::get_InterfaceID

The get_InterfaceID method obtains an interface identifier of this scope, which identifies the interface on which the server that published this scope resides. This is normally the network address of the interface.

HRESULT get_InterfaceID(
  long *pID
);

Parameters

pID
[out] Pointer to a LONG that will receive the server ID of this scope, which is the ID that was assigned to the multicast address allocation server that published this scope at the time that the server was configured.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The caller passed in an invalid pointer argument.

Remarks

The InterfaceID is provided for informational purposes only; it is not required as input to any of the methods in these interfaces. However, it may factor into the application's (or the user's) decision as to which scope to use when requesting an address. This is because, in a multihomed scenario, using a multicast address on one network that was obtained from a server on another network may cause address conflicts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mdhcp.h.
Library: Use Mdhcpid.lib.

See Also

IMcastScope


ITAttributeList

The ITAttributeList interface supplies methods for getting and setting of uninterpreted attributes. Regarding the position of the attribute strings in a Session Descriptor Protocol (SDP, see RFC 2327) packet, the methods assume that all attribute strings exist just before the media attributes are specified and after all the common attributes.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITAttributeList methods | Description
get_Count | Gets the number of attributes.
get_Item | Gets the attribute specified by the index.
Add | Adds the attribute at the specified index.
Delete | Deletes the attribute at the specified index
get_AttributeList | Gets the list of attributes.
put_AttributeList | Sets the list of attributes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


ITAttributeList::get_Count

The get_Count method gets the number of attributes.

HRESULT get_Count(
  LONG *pVal
);

Parameters

pVal
[out] Count of the attributes in the list.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITAttributeList


ITAttributeList::get_AttributeList

The get_AttributeList method gets the list of attributes.

HRESULT get_AttributeList(
  VARIANT *pVal
);

Parameters

pVal
[out] Array of attributes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITAttributeList, ITAttributeList::put_AttributeList


ITAttributeList::put_AttributeList

The put_AttributeList method sets the list of attributes.

HRESULT put_AttributeList(
  VARIANT newVal
);

Parameters

newVal
[in] Array of attributes to set.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The newVal parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITAttributeList, ITAttributeList::get_AttributeList


ITAttributeList::get_Item

The get_Item method returns the attribute specified by the index.

HRESULT get_Item(
  LONG Index,
  BSTR *pVal
);

Parameters

Index
[in] Index of the item to get.
pVal
[out] Pointer to a BSTR containing the values of the item.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_INVALIDARG | The Index parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the pVal parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITAttributeList


ITAttributeList::Add

The Add method adds the attribute at the specified index.

HRESULT Add(
  LONG Index,
  BSTR pAttribute
);

Parameters

Index
[in] Index of the attribute to add.
pAttribute
[in] Pointer to a BSTR containing the value of the attribute to add.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Index or pAttribute parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pAttribute parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITAttributeList


ITAttributeList::Delete

The Delete method deletes the attribute at the specified index.

HRESULT Delete(
  LONG Index
);

Parameters

Index
[in] Index of the attribute to delete.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Index parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITAttributeList


ITConferenceBlob

The ITConferenceBlob interface manipulates a textual conference description. The interface is meant to be independent of the format and syntax of the conference description. To manipulate specific aspects of the conference description, the application must query for another interface. Currently, only SDP conference descriptions are supported; the application must QueryInterface for ITSdp to access the various fields of the SDP conference description.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITConferenceBlob methods | Description
Init | Initializes the conference blob.
get_CharacterSet | Gets the BLOB_CHARACTER_SET indicator of whether blob characters are in ASCII, Unicode, etc.
get_ConferenceBlob | Gets a pointer to the conference blob.
SetConferenceBlob | Commits changes to the conference blob.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


ITConferenceBlob::Init

The Init method initializes the conference blob based on a textual string. If pBlob is NULL, default values are used.

HRESULT Init(
  BSTR pName,
  BLOB_CHARACTER_SET CharacterSet,
  BSTR pBlob
);

Parameters

pName
[in] Pointer to a BSTR representation of the conference name.
CharacterSet
[in] BLOB_CHARACTER_SET descriptor of the character set.
pBlob
[in] Pointer to a BSTR containing the conference blob. If NULL, the conference blob is initialized with default values. Currently, default conference values are available only if the CharacterSet parameter is set to BCS_ASCII.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pName, CharacterSet, or pBlob parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

ITConferenceBlob::Init will return a failure if the blob has already been initialized.

The application must use SysAllocString to allocate memory for the pName and pBlob parameters. The application must use SysFreeString to free the memory when the variables are no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConferenceBlob, BLOB_CHARACTER_SET


ITConferenceBlob::get_CharacterSet

The get_CharacterSet method gets a BLOB_CHARACTER_SET descriptor of the character set used in the current conference blob.

HRESULT get_CharacterSet(
    BLOB_CHARACTER_SET *pCharacterSet
);

Parameters

pCharacterSet
[out, retval] Pointer to a BLOB_CHARACTER_SET descriptor of the character set.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pCharacterSet parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.
E_INVALIDARG | pCharacterSet is NULL.
(HRESULT) ERROR_INVALID_DATA | The current character set is invalid or unavailable.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConferenceBlob, BLOB_CHARACTER_SET


ITConferenceBlob::get_ConferenceBlob

The get_ConferenceBlob method gets a pointer to the textual conference blob currently stored in the conference blob object.

HRESULT get_ConferenceBlob(
  BSTR *ppBlob
);

Parameters

ppBlob
[out] Pointer to a BSTR containing the conference blob.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppBlob parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppBlob parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConferenceBlob, BLOB_CHARACTER_SET


ITConferenceBlob::SetConferenceBlob

The SetConferenceBlob method commits changes to the conference blob. To initialize the conference blob for the first time, use the Init method instead.

HRESULT SetConferenceBlob(
  BLOB_CHARACTER_SET CharacterSet,
  BSTR pBlob
);

Parameters

CharacterSet
[in] BLOB_CHARACTER_SET descriptor of the conference blob's character set.
pBlob
[in] Pointer to a BSTR containing the conference blob.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The CharacterSet or pBlob parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pBlob parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConferenceBlob, BLOB_CHARACTER_SET


ITConnection

The ITConnection interface provides the following functionality:

  • Provides access to the address and time to live (TTL) information for the session.
  • Provides access to the bandwidth information.
  • Enables manipulation of the encryption key.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITConnection methods | Description
get_NetworkType | Gets the network type.
put_NetworkType | Sets the network type.
get_AddressType | Gets the address type.
put_AddressType | Sets the address type.
get_StartAddress | Gets the first address to be used for the session.
get_NumAddresses | Gets the number of addresses to be used for the session.
get_Ttl | Gets the TTL (time to live) scope for transmissions on the addresses.
get_BandwidthModifier | Gets the bandwidth modifier.
get_Bandwidth | Gets bandwidth value.
SetAddressInfo | Sets address information.
SetBandwidthInfo | Sets the bandwidth value.
SetEncryptionKey | Sets the encryption key needed to decrypt the session or an indication to a mechanism to obtain a usable key by external means.
GetEncryptionKey | Gets the encryption key.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


ITConnection::get_NetworkType

The get_NetworkType method gets the network type.

HRESULT get_NetworkType(
  BSTR *ppNetworkType
);

Parameters

ppNetworkType
[out] Pointer to a BSTR containing the network type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppNetworkType parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppNetworkType parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection, ITConnection::put_NetworkType


ITConnection::put_NetworkType

The put_NetworkType method sets the network type.

HRESULT put_NetworkType(
  BSTR pNetworkType
);

Parameters

pNetworkType
[in] Pointer to a BSTR containing the network type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pNetworkType parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pNetworkType parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection, ITConnection::get_NetworkType


ITConnection::get_AddressType

The get_AddressType method gets the address type.

HRESULT get_AddressType(
  BSTR *ppAddressType
);

Parameters

ppAddressType
[out] Pointer to a BSTR containing the address type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppAddressType parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppAddressType parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection, ITConnection::put_AddressType


ITConnection::put_AddressType

The put_AddressType method sets the address type.

HRESULT put_AddressType(
  BSTR pAddressType
);

Parameters

pAddressType
[in] Pointer to a BSTR containing the address type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pAddressType parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pAddressType parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection, ITConnection::get_AddressType


ITConnection::get_StartAddress

The get_StartAddress method gets the first address to be used for the session.

HRESULT get_StartAddress(
  BSTR *ppStartAddress
);

Parameters

ppStartAddress
[out] Pointer to a BSTR containing the starting address for the session.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppStartAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppStartAddress parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::get_NumAddresses

The get_NumAddresses method gets the number of addresses to be used for the session.

HRESULT get_NumAddresses(
  LONG *pNumAddresses
);

Parameters

pNumAddresses
[out] Number of addresses for the session.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pNumAddresses parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::get_Ttl

The get_Ttl method gets the time to live (TTL) scope for transmissions on the addresses.

HRESULT get_Ttl(
  unsigned char *pTtl
);

Parameters

pTtl
[out] TTL scope.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTtl parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::get_BandwidthModifier

The get_BandwidthModifier method gets the bandwidth modifier, which is a single, alphanumeric word giving the meaning of the bandwidth figure. The two modifiers defined are CT (Conference Total) and AS (Application Specific Maximum).

HRESULT get_BandwidthModifier(
  BSTR *ppModifier
);

Parameters

ppModifier
[out] Pointer to a BSTR containing the bandwidth modifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppModifier parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppModifier parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::get_Bandwidth

The get_Bandwidth method gets the bandwidth value.

HRESULT get_Bandwidth(
  DOUBLE *pBandwidth
);

Parameters

pBandwidth
[out] Bandwidth value.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pBandwidth parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::SetAddressInfo

The SetAddressInfo method sets the address information.

HRESULT SetAddressInfo(
  BSTR pStartAddress,
  LONG NumAddresses,
  unsigned char Ttl
);

Parameters

pStartAddress
[in] Pointer to a BSTR containing the start address.
NumAddresses
[in] Number of addresses to be used for the session.
Ttl
[in] TTL (time to live) scope for transmissions on the addresses.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pStartAddress, NumAddresses, or Ttl parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pStartAddress parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::SetBandwidthInfo

The SetBandwidthInfo method sets the bandwidth information.

HRESULT SetBandwidthInfo(
  BSTR pModifier,
  DOUBLE Bandwidth
);

Parameters

pModifier
[in] Pointer to a BSTR indicating the scope of the bandwidth being set. For more information, see the following Remarks section.
Bandwidth
[in] Bandwidth.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pModifier or Bandwidth parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pModifier parameter and use SysFreeString to free the memory when the variable is no longer needed.

Reference: RFC 2327.

The bandwidth modifier will normally be either CT or AS:

CT Conference Total: An implicit maximum bandwidth is associated with each TTL on the Mbone or within a particular multicast administrative scope region (the Mbone bandwidth versus TTL limits are given in the MBone FAQ). If the bandwidth of a session or media in a session is different from the bandwidth implicit from the scope, a `b=CT:...' line should be supplied for the session giving the proposed upper limit to the bandwidth used. The primary purpose of this is to give an approximate idea as to whether two or more conferences can coexist simultaneously.

AS Application-Specific Maximum: The bandwidth is interpreted to be application-specific, i.e., will be the application's concept of maximum bandwidth. Normally this will coincide with what is set on the application's "maximum bandwidth" control, if applicable.

Note that CT gives a total bandwidth figure for all the media at all sites. AS gives a bandwidth figure for a single media at a single site, although there may be many sites sending simultaneously.

Extension Mechanism: Tool writers can define experimental bandwidth modifiers by prefixing their modifiers with "X-".

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::SetEncryptionKey

The SetEncryptionKey method sets the encryption key needed to decrypt the session or an indication to a mechanism to obtain a usable key by external means.

HRESULT SetEncryptionKey(
 BSTR pKeyType,
 BSTR *ppKeyData
);

Parameters

pKeyType
[in] Pointer to a BSTR containing the encryption key type.
ppKeyData
[in] Pointer to a BSTR containing encryption key information.

Return Values

Value | Meaning
S_OK | Method succeeded.

Remarks

The application must use SysAllocString to allocate memory for the pKeyType and ppKeyData parameters. The application must use SysFreeString to free the memory when the variables are no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITConnection::GetEncryptionKey

The GetEncryptionKey method gets the encryption key.

HRESULT GetEncryptionKey(
 BSTR *ppKeyType,
 VARIANT_BOOL *pfValidKeyData,
 BSTR *ppKeyData
);

Parameters

ppKeyType
[out] Pointer to a BSTR containing the type of encryption key.
pfValidKeyData
[out] Indicates validity of encryption key data.
ppKeyData
[out] Pointer to a BSTR containing the encryption key data.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppKeyType, pfValidKeyData, or ppKeyData parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppKeyType and ppKeyData parameters.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITConnection


ITDirectory

The ITDirectory interface is exposed by the Directory object, which corresponds to a particular directory. This interface provides methods that get and set directory information, and provide access to a particular directory object, such a conference or user.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDirectory methods | Description
get_DirectoryType | Gets the type of the directory.
get_DisplayName | Gets the displayable name for the directory.
get_IsDynamic | Gets an indicator of whether the object on the server needs to be refreshed.
get_DefaultObjectTTL | Gets the default time to live (TTL) for the objects created.
put_DefaultObjectTTL | Sets the default TTL for the objects created.
EnableAutoRefresh | Enables the auto refresh for the objects created afterward.
Connect | Connects to the server.
Bind | Binds to the server.
AddDirectoryObject | Adds an object to the server.
ModifyDirectoryObject | Commits directory modifications to the server.
RefreshDirectoryObject | Refreshes the TTL for an object on the server.
DeleteDirectoryObject | Deletes an object from the server.
get_DirectoryObjects | Gets all directory objects on the server with a specified type and name.
EnumerateDirectoryObjects | Creates an enumeration of directory objects of a given type and name.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

Directory Controls


ITDirectory::get_DirectoryType

The get_DirectoryType method gets DIRECTORY_TYPE indicator of the type of the directory.

HRESULT get_DirectoryType(
  DIRECTORY_TYPE *pDirectoryType
);

Parameters

pDirectoryType
[out] Pointer to type of the directory.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDirectoryType parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory, DIRECTORY_TYPE


ITDirectory::get_DisplayName

The get_DisplayName method gets displayable name for directory.

HRESULT get_DisplayName(
  BSTR *pName
);

Parameters

pName
[out] Pointer to a BSTR representation of the directory name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the pName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::get_IsDynamic

The get_IsDynamic method gets an indicator of whether the object on the server needs to be refreshed.

HRESULT get_IsDynamic(
  VARIANT_BOOL *pfDynamic
);

Parameters

pfDynamic
[out] Pointer to a Boolean VARIANT; VARIANT_TRUE if server needs to be refreshed and VARIANT_FALSE if it does not.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pfDynamic parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::get_DefaultObjectTTL

The get_DefaultObjectTTL method gets the default time to live (TTL) value, in seconds, for objects created. Only applies to dynamic servers.

HRESULT get_DefaultObjectTTL(
  long *pTTL
);

Parameters

pTTL
[out] Pointer to TTL value, in seconds.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTTL parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory, ITDirectory::put_DefaultObjectTTL


ITDirectory::put_DefaultObjectTTL

The put_DefaultObjectTTL method sets the default time to live (TTL) value, in seconds, for objects created. Only applies to dynamic servers. The minimum value is 300 seconds.

HRESULT put_DefaultObjectTTL(
  long TTL
);

Parameters

TTL
[in] TTL value, in seconds.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The TTL parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory, ITDirectory::get_DefaultObjectTTL


ITDirectory::EnableAutoRefresh

The EnableAutoRefresh method enables auto refresh for directory objects created after it is called. Only applies to dynamic servers.

HRESULT EnableAutoRefresh(
  VARIANT_BOOL fEnable
);

Parameters

fEnable
[in] Set to VARIANT_TRUE if auto refresh is to be enabled.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The fEnable parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::Connect

The Connect method establishes a connection to the directory server.

HRESULT Connect(
  VARIANT_BOOL fSecure
);

Parameters

fSecure
[in] Boolean indicator of whether to use SSL connection.

Return Values

Value | Meaning
S_OK | Method succeeded.
RND_ALREADY_CONNECTED | A successful connection has already been made.
RND_NULL_SERVER_NAME | The server name is NULL, probably because ITConferenceBlob::Init has not been run or did not succeed.

Remarks

The Connect method must be successfully called before any other function except get_DirectoryType.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::Bind

The Bind method binds to the server.

HRESULT Bind(
  BSTR pDomainName,
  BSTR pUserName,
  BSTR pPassword,
  long lFlags
);

Parameters

pDomainName
[in] Pointer to a BSTR containing the user's domain name.
pUserName
[in] Pointer to a BSTR containing the user's name.
pPassword
[in] Pointer to a BSTR containing the user's password.
lFlags
[in] RENDBIND flags indicator of whether all parameters must be validated or can take a default.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDomainName, pUserName, or pPassword parameter is not a valid pointer.
E_INVALIDARG | A password is required but was not supplied, the domain and user are not supplied, or the domain was supplied but the user was not.
RND_NOT_CONNECTED | The ITDirectory::Connect method has not been invoked or did not succeed.

Remarks

The input variables pDomainName, pUserName, and pPassword can be NULL.

Calling this function is optional. However, some directory operations require the user to be authenticated first. It is always safe to call Bind.

The application must use SysAllocString to allocate memory for the pDomainName, pUserName, and pPassword parameters. The application must use SysFreeString to free the memory when the variables are no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::AddDirectoryObject

The AddDirectoryObject method adds an ITDirectoryObject object to the server. This may be a directory or a user machine mapping.

HRESULT AddDirectoryObject(
  ITDirectoryObject *pDirectoryObject
);

Parameters

pDirectoryObject
[in] The object that will be added into the directory.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDirectoryObject parameter is not a valid pointer.
RND_NOT_CONNECTED | The ITDirectory::Connect method has not been invoked or did not succeed.
E_NOTIMPL | This method is not implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::ModifyDirectoryObject

The ModifyDirectoryObject method commits directory modifications to the server.

HRESULT ModifyDirectoryObject(
  ITDirectoryObject *pDirectoryObject
);

Parameters

pDirectoryObject
[in] Pointer to ITDirectoryObject modified.

Remarks

Changes made to ITDirectoryObject will not take effect on the server until this method is called.

Some attributes cannot be modified, and an attempt to modify them will fail. For an example, see the Remarks section of ITDirectoryObjectUser::put_IPPhonePrimary.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDirectoryObject parameter is not a valid pointer.
RND_NOT_CONNECTED | The ITDirectory::Connect method has not been invoked or did not succeed.
E_NOTIMPL | This method is not implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::RefreshDirectoryObject

The RefreshDirectoryObject method refreshes the time to live (TTL) for an object on the server. Only applies to dynamic servers.

HRESULT RefreshDirectoryObject(
  ITDirectoryObject *pDirectoryObject
);

Parameters

pDirectoryObject
[in] Pointer to ITDirectoryObject to be refreshed.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDirectoryObject parameter is not a valid pointer.
RND_NOT_CONNECTED | The ITDirectory::Connect method has not been invoked or did not succeed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::DeleteDirectoryObject

The DeleteDirectoryObject method deletes an object from the server.

HRESULT DeleteDirectoryObject(
  ITDirectoryObject *pDirectoryObject
);

Parameters

pDirectoryObject
[in] Pointer to ITDirectoryObject that will be deleted from the directory.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDirectoryObject parameter is not a valid pointer.
RND_NOT_CONNECTED | The ITDirectory::Connect method has not been invoked or did not succeed.
E_NOTIMPL | This method is not implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory


ITDirectory::get_DirectoryObjects

The get_DirectoryObjects method gets the collection of objects in a given directory that matches certain criteria. This method performs the same function as EnumerateDirectoryObjects but is used by Visual Basic and other scripting languages.

HRESULT get_DirectoryObjects(
  DIRECTORY_OBJECT_TYPE DirectoryObjectType,
  BSTR pName,
  VARIANT *pVariant
);

Parameters

DirectoryObjectType
[in] The DIRECTORY_OBJECT_TYPE criteria for object desired.
pName
[in] Pointer to a BSTR containing the full or partial name of the object. The "*" wildcard is supported.
pVariant
[out, retval] Pointer to a VARIANT that receives an ITCollection of ITDirectoryObject objects in the server that match the description.

Return Values

Value | Meaning
S_OK | Method succeeded.
RND_NOT_CONNECTED | The ITDirectory::Connect method has not been invoked or did not succeed.
E_NOTIMPL | This method is not implemented.

Remarks

The application must use SysAllocString to allocate memory for the pName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory, DIRECTORY_OBJECT_TYPE, ITCollection, ITDirectoryObject


ITDirectory::EnumerateDirectoryObjects

The EnumerateDirectoryObjects method creates an enumeration of directory objects of a given type and name.

HRESULT EnumerateDirectoryObjects(
  DIRECTORY_OBJECT_TYPE DirectoryObjectType,
  BSTR pName,
  IEnumDirectoryObject **ppEnumObject
);

Parameters

DirectoryObjectType
[in] The DIRECTORY_OBJECT_TYPE criteria for object desired.
pName
[in] Pointer to a BSTR containing the full or partial name of the object. The "*" wildcard is supported.
ppEnumObject
[out] Pointer to receive IEnumDirectoryObject interface pointer for the enumerator of matching objects.

Return Values

Value | Meaning
S_OK | Method succeeded.
RND_NOT_CONNECTED | The ITDirectory::Connect method has not been invoked or did not succeed.
E_NOTIMPL | This method is not implemented.

Remarks

The application must use SysAllocString to allocate memory for the pName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectory, DIRECTORY_OBJECT_TYPE


ITDirectoryObject

The ITDirectoryObject interface is the common interface supported by all objects that can be added and deleted by using the ITDirectory interface. Changes made to this object will not take effect on the server until the ITDirectory::ModifyDirectoryObject method is called.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDirectoryObject methods | Description
get_ObjectType | Gets the type of this directory.
get_Name | Gets the name of this directory.
put_Name | Sets the name of this directory.
get_DialableAddrs | Gets a dialable address for this directory.
EnumerateDialableAddrs | Enumerates dialable addresses.
get_SecurityDescriptor | Gets the security descriptor.
put_SecurityDescriptor | Sets the security descriptor.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


ITDirectoryObject::get_Name

The get_Name method gets the name of the directory object.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to BSTR representation of directory name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | Invalid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObject, ITDirectoryObject::put_Name


ITDirectoryObject::put_Name

The put_Name method sets the name of the directory object.

HRESULT put_Name(
  BSTR pName
);

Parameters

pName
[in] Pointer to BSTR representation of directory name.

Remarks

Changes made will not take effect on the server until the ITDirectory::ModifyDirectoryObject method is called.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObject, ITDirectoryObject::get_Name


ITDirectoryObject::get_ObjectType

The get_ObjectType method gets a DIRECTORY_OBJECT_TYPE descriptor of the object.

HRESULT get_ObjectType(
  DIRECTORY_OBJECT_TYPE *pObjectType
);

Parameters

pObjectType
[out] Pointer to descriptor of directory object type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | Invalid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObject, DIRECTORY_OBJECT_TYPE


ITDirectoryObject::get_DialableAddrs

The get_DialableAddrs method gets all dialable addresses of a given type from the directory. This method performs the same function as EnumerateDialableAddrs but is used by scripting languages such as Visual Basic.

HRESULT get_DialableAddrs(
  long dwAddressType,
  VARIANT *pVariant
);

Parameters

dwAddressType
[in] Indicator of address type.
pVariant
[out] Pointer to a VARIANT containing an ITCollection of ITAddress interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | Invalid pointer.
ERROR | Method failed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObject


ITDirectoryObject::EnumerateDialableAddrs

The EnumerateDialableAddrs method creates an enumerator of all dialable addresses of a given type from the directory.

HRESULT EnumerateDialableAddrs(
  DWORD dwAddressType,
  IEnumDialableAddrs **ppEnumDialableAddrs
);

Parameters

dwAddressType
[in] Indicator of the address type.
ppEnumDialableAddrs
[out] Pointer to the IEnumDialableAddrs interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | Invalid pointer.
ERROR | Method failed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObject


ITDirectoryObject::get_SecurityDescriptor

The get_SecurityDescriptor method gets an IDispatch pointer on a directory service security descriptor object describing current security permissions. For additional information on security descriptors, please search the Platform SDK under "IADsSecurityDescriptor".

HRESULT get_SecurityDescriptor(
  IDispatch **ppSecDes
);

Parameters

ppSecDes
[out] IDispatch pointer on a directory service security descriptor object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppSecDes parameter is not a valid pointer.
E_FAIL | Initialization of security descriptor failed.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

If the security descriptor has not been set, this method will set ppSecDes to NULL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObject, ITDirectoryObject::put_SecurityDescriptor


ITDirectoryObject::put_SecurityDescriptor

The put_SecurityDescriptor method sets an IDispatch pointer on a directory service security descriptor object describing current security permissions. For additional information on security descriptors, please search the Platform SDK under "IADsSecurityDescriptor".

HRESULT put_SecurityDescriptor(
  IDispatch *pSecDes
);

Parameters

pSecDes
[in] IDispatch pointer on a directory service security descriptor object.

Remarks

Changes made will not take effect on the server until the ITDirectory::ModifyDirectoryObject method is called.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pSecDes parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObject, ITDirectoryObject::get_SecurityDescriptor


ITDirectoryObjectConference

The ITDirectoryObjectConference interface provides methods that allow an application to set and get conference details.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDirectoryObjectConference methods | Description
get_Protocol | Gets protocol identification.
get_Originator | Gets conference originator.
put_Originator | Sets originator.
get_AdvertisingScope | Gets advertising scope.
put_AdvertisingScope | Sets advertising scope.
get_Url | Gets URL.
put_Url | Sets URL.
get_Description | Gets description of conference.
put_Description | Sets description of conference.
get_IsEncrypted | Gets whether conference is encrypted.
put_IsEncrypted | Sets whether conference is encrypted.
get_StartTime | Gets start time of conference.
put_StartTime | Sets start time of conference.
get_StopTime | Gets stop time of conference.
put_StopTime | Sets stop time of conference.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


ITDirectoryObjectConference::get_Protocol

The get_Protocol method gets protocol identification.

HRESULT get_Protocol(
  BSTR *ppProtocol
);

Parameters

ppProtocol
[out] Pointer to a BSTR containing the protocol identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppProtocol parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppProtocol parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference


ITDirectoryObjectConference::get_Originator

The get_Originator method gets the originator's user name.

HRESULT get_Originator(
  BSTR *ppOriginator
);

Parameters

ppOriginator
[out] Pointer to a BSTR containing the originator's user name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppOriginator parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppOriginator parameter.

The originator's name, along with the machine name set in put_MachineAddress, are collectively the originator of the conference, and both are in the o= line of the SDP.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::put_Originator


ITDirectoryObjectConference::put_Originator

The put_Originator method sets the originator's user name.

HRESULT put_Originator(
  BSTR pOriginator
);

Parameters

pOriginator
[in] Pointer to a BSTR containing the originator's user name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pOriginator parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pOriginator parameter and use SysFreeString to free the memory when the variable is no longer needed.

The originator's name, along with the machine name set in put_MachineAddress, are collectively the originator of the conference, and both are in the o= line of the SDP.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::get_Originator


ITDirectoryObjectConference::get_AdvertisingScope

The get_AdvertisingScope method gets the advertising scope.

HRESULT get_AdvertisingScope(
  RND_ADVERTISING_SCOPE *pAdvertisingScope
);

Parameters

pAdvertisingScope
[out] Pointer to RND_ADVERTISING_SCOPE enumeration.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pAdvertisingScope parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::put_AdvertisingScope, RND_ADVERTISING_SCOPE


ITDirectoryObjectConference::put_AdvertisingScope

The put_AdvertisingScope method sets the advertising scope.

HRESULT put_AdvertisingScope(
  RND_ADVERTISING_SCOPE AdvertisingScope
);

Parameters

AdvertisingScope
[in] Pointer to RND_ADVERTISING_SCOPE enumeration.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The AdvertisingScope parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::get_AdvertisingScope, RND_ADVERTISING_SCOPE


ITDirectoryObjectConference::get_Url

The get_Url method gets a URL.

HRESULT get_Url(
  BSTR *ppUrl
);

Parameters

ppUrl
[out] Pointer to a BSTR containing the URL.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppUrl parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppUrl parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::put_Url


ITDirectoryObjectConference::put_Url

The put_Url method sets a URL.

HRESULT put_Url(
  BSTR pUrl
);

Parameters

pUrl
[in] Pointer to a BSTR containing the URL.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pUrl parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pUrl parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::get_Url


ITDirectoryObjectConference::get_Description

The get_Description method gets the description of the conference.

HRESULT get_Description(
  BSTR *ppDescription
);

Parameters

ppDescription
[out] Pointer to a BSTR containing the description of the conference.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppDescription parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppDescription parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::put_Description


ITDirectoryObjectConference::put_Description

The put_Description method sets the description of the conference.

HRESULT put_Description(
  BSTR pDescription
);

Parameters

pDescription
[in] Pointer to a BSTR containing the description of the conference.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDescription parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pDescription parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::get_Description


ITDirectoryObjectConference::get_IsEncrypted

The get_IsEncrypted method gets whether the conference is encrypted.

HRESULT get_IsEncrypted(
  VARIANT_BOOL *pfEncrypted
);

Parameters

pfEncrypted
[out] Pointer to whether the conference is encrypted.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pfEncrypted parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::put_IsEncrypted


ITDirectoryObjectConference::put_IsEncrypted

The put_IsEncrypted method sets whether the conference is encrypted.

HRESULT put_IsEncrypted(
  VARIANT_BOOL fEncrypted
);

Parameters

fEncrypted
[in] Indicator of whether the conference is encrypted.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The fEncrypted parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::get_IsEncrypted


ITDirectoryObjectConference::get_StartTime

The get_StartTime method gets the start time of the conference.

HRESULT get_StartTime(
  DATE *pDate
);

Parameters

pDate
[out] Pointer to the conference start time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDate parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::put_StartTime


ITDirectoryObjectConference::put_StartTime

The put_StartTime method sets the start time of the conference.

HRESULT put_StartTime(
  DATE Date
);

Parameters

Date
[in] Conference start time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Date parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::get_StartTime


ITDirectoryObjectConference::get_StopTime

The get_StopTime method gets the stop time of the conference. If the end time is zero, the session is not bounded.

HRESULT get_StopTime(
  DATE *pDate
);

Parameters

pDate
[out] Pointer to the conference stop time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDate parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::put_StopTime


ITDirectoryObjectConference::put_StopTime

The put_StopTime method sets the stop time of the conference. If the end time is zero, the session is not bounded.

HRESULT put_StopTime(
  DATE Date
);

Parameters

Date
[in] Conference stop time.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Date parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectConference, ITDirectoryObjectConference::get_StopTime


ITDirectoryObjectUser

The ITDirectoryObjectUser interface is the common interface supported by the User object.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITDirectoryObjectUser methods | Description
get_IPPhonePrimary | Gets user's primary IP phone.
put_IPPhonePrimary | Sets user's primary IP phone.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


ITDirectoryObjectUser::get_IPPhonePrimary

The get_IPPhonePrimary method gets the name of a computer that is the primary IP phone for the user.

HRESULT get_IPPhonePrimary(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to the BSTR representation of the user's IP primary phone.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | Invalid pointer.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectUser, ITDirectoryObjectUser::put_IPPhonePrimary


ITDirectoryObjectUser::put_IPPhonePrimary

The put_IPPhonePrimary method sets the name of a machine as the primary IP phone for a user.

HRESULT put_IPPhonePrimary(
  BSTR pName
);

Parameters

pName
[in] Pointer to the BSTR representation of the user's IP primary phone.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | Invalid pointer.

Remarks

This method can be used only on a new object that is subsequently added to the directory. If an application wants to modify the IP phone of an existing user object, it has to enumerate the objects from the server to determine the old IP phones are. This implies that a TAPI 3.0 application is running on one or more other machines. The application on a local machine has no information about whether those other applications are still running. Therefore, it is not the application's place to change the IP Phone on existing user objects.

To modify an existing user's IP Phone, the user must be deleted and re-added.

The application must use SysAllocString to allocate memory for the pName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITDirectoryObjectUser, ITDirectoryObjectUser::get_IPPhonePrimary


ITILSConfig

The ITILSConfig interface allows configuration of the ILS directory. This interface is available only on Directory objects that return DT_ILS from ITDirectory::get_DirectoryType.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITILSConfig methods | Description
get_Port | Gets the port number used to connect to the server of a given ILS directory.
put_Port | Sets the port number used to connect to the server of a given ILS directory.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


ITILSConfig::get_Port

The get_Port method gets the port number used to connect to the server of a given ILS directory.

HRESULT get_Port(
  long *pPort
);

Parameters

pPort
[out] Pointer to receive the port number used in the connection.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | Invalid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITILSConfig, ITILSConfig::put_Port


ITILSConfig::put_Port

The put_Port method sets the port number used to connect to the server of a specified ILS directory.

HRESULT put_Port(
  long Port
);

Parameters

Port
[in] The port number that will be used to connect to the server. This can be any port number in the range of 16-bit unsigned integers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Port parameter is not valid.
RND_ALREADY_CONNECTED | A successful connection has been made. Port cannot be reset.

Remarks

Applications use this method only if they need to connect to custom-configured ILS servers listening on strange ports that are not listed in the Active Directory. By default, the Rendezvous control automatically tries to use ports 1002 and 389, the usual ILS ports, for connecting to application-specified ILS servers. Also, the Rendezvous control automatically uses whatever port is published in the Active Directory for ILS servers retrieved from there.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITILSConfig, ITILSConfig::get_Port


ITMedia

The ITMedia interface is a representation of media in a Session Descriptor Protocol (SDP, see RFC 2327). This interface exports methods to get and set basic media properties, such as type.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITMedia methods | Descriptions
get_MediaName | Gets the media name.
put_MediaName | Sets the media name.
get_StartPort | Gets the 16-bit port value for the first port.
get_NumPorts | Gets the number of ports needed for the session.
get_TransportProtocol | Gets the transport protocol.
put_TransportProtocol | Sets the transport protocol.
get_FormatCodes | Gets the list of media payload format codes.
put_FormatCodes | Sets the list of media payload format codes.
get_MediaTitle | Gets the media title.
put_MediaTitle | Sets the media title.
SetPortInfo | Sets the 16-bit port value for the first port and number of ports needed for session.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMediaCollection, ITSDP, ITTime


ITMedia::get_MediaName

The get_MediaName method gets the media name. Defined media are audio, video, whiteboard, text, and data.

HRESULT get_MediaName(
  BSTR *ppMediaName
);

Parameters

ppMediaName
[out] Pointer to a BSTR containing the name of the media, such as audio.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppMediaName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppMediaName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::put_MediaName


ITMedia::get_TransportProtocol

The get_TransportProtocol method gets the transport protocol. This is specified in addition to the media format so that the same standard media format may be carried over different transport protocols even when the network protocol is the same, such as with Vat PCM audio and RTP PCM audio.

HRESULT get_TransportProtocol(
  BSTR *ppProtocol
);

Parameters

ppProtocol
[out] Pointer to the BSTR representation of the transport protocol.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppProtocol parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppProtocol parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::put_TransportProtocol


ITMedia::get_FormatCodes

The get_FormatCodes method gets the list of media payload format codes. The variant returns a SAFEARRAY of BSTRs. Each BSTR within that array is a format code string.

HRESULT get_FormatCodes(
  VARIANT *pVal
);

Parameters

pVal
[out] Array of media payload format codes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

When a list of payload formats is given, this implies that all of these formats may be used in the session, but the first of these formats is the default format for the session. When the transport protocol is RTP, the format codes are RTP payload types.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::put_FormatCodes


ITMedia::get_MediaTitle

The get_MediaTitle method retrieves a textual title for the media that the application can use for informational or display purposes. This must be an ASCII convertible string if the character set is ASCII. Otherwise, it can be any BSTR string.

HRESULT get_MediaTitle(
  BSTR *ppMediaTitle
);

Parameters

ppMediaTitle
[out] Pointer to a BSTR containing the title of the media.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppMediaTitle parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppMediaTitle parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::Put_MediaTitle


ITMedia::put_MediaName

The put_MediaName method sets the media name. Defined media are audio, video, whiteboard, text, and data.

HRESULT put_MediaName(
  BSTR pMediaName
);

Parameters

pMediaName
[in] Pointer to a BSTR containing the media name to set.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pMediaName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pMediaName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::get_MediaName


ITMedia::get_StartPort

The get_StartPort method gets the 16-bit port value for the first port.

HRESULT get_StartPort(
  LONG *pStartPort
);

Parameters

pStartPort
[out] Value of the first port.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pStartPort parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia


ITMedia::put_TransportProtocol

The put_TransportProtocol method sets the transport protocol. This is specified in addition to the media format so that the same standard media format may be carried over different transport protocols even when the network protocol is the same, such as with Vat PCM audio and RTP PCM audio.

HRESULT put_TransportProtocol(
  BSTR pProtocol
);

Parameters

pProtocol
[in] Pointer to a BSTR containing the transport protocol.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pProtocol parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pProtocol parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::get_TransportProtocol


ITMedia::put_FormatCodes

The put_FormatCodes method sets the list of media payload format codes. The variant contains a SAFEARRAY of BSTRs. Each BSTR within that array is a format code string.

HRESULT put_FormatCodes(
  VARIANT NewVal
);

Parameters

NewVal
[in] List of media payload format codes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The NewVal parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

When a list of payload formats is given, this implies that all of these formats may be used in the session, but the first of these formats is the default format for the session. When the transport protocol is RTP, the format codes are RTP payload types.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::get_FormatCodes


ITMedia::put_MediaTitle

The put_MediaTitle method sets a textual title for the media that the application can use for informational or display purposes. This must be an ASCII convertible string if the character set is ASCII. Otherwise, it can be any BSTR string.

HRESULT put_MediaTitle(
  BSTR pMediaTitle
);

Parameters

pMediaTitle
[in] Pointer to a BSTR containing the title of the media.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pMediaTitle parameter is not a valid pointer.
E_INVALIDARG | The pMediaTitle parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pMediaTitle parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia, ITMedia::get_MediaTitle


ITMedia::SetPortInfo

The SetPortInfo method sets the 16-bit port value for the first port and the number of ports needed for a session.

HRESULT SetPortInfo(
  LONG StartPort,
  LONG NumPorts
);

Parameters

StartPort
[in] Starting port. This can be a value in the range 0-65535.
NumPorts
[in] Number of ports. This can be a value in the range 0-65535.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The StartPort or NumPorts parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia


ITMedia::get_NumPorts

The get_NumPorts method gets the number of ports needed for the session. The session uses the specified number of ports starting from the value returned by get_StartPort.

HRESULT get_NumPorts(
  LONG *pNumPorts
);

Parameters

pNumPorts
[out] Pointer to the number of ports.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pNumPorts parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMedia


ITMediaCollection

The ITMediaCollection interface provides access to the set of media information in an SDP (RFC 2327) conference description. Each Media description in the SDP is described by an ITMedia interface. ITMediaCollection allows manipulation of the set of ITMedia information for the SDP, including:

  • Allows media access by index.
  • Enables creation and deletion of media.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITMediaCollection methods | Description
get_Count | Gets the number of media in the session.
get_Item | Returns the media corresponding to the specified index.
get__NewEnum | Returns an enumerator for the collection.
get_EnumerationIf | Gets pointer to enumeration interface.
Create | Creates a new media with default properties and returns it.
Delete | Deletes the media corresponding to the specified index.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


ITMediaCollection::get_Count

The get_Count method gets the number of media in the session.

HRESULT get_Count(
  LONG *pVal
);

Parameters

pVal
[out] Count of media in the session.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMediaCollection


ITMediaCollection::get_EnumerationIf

The get_EnumerationIf method gets a pointer to a media enumeration interface.

HRESULT get_EnumerationIf(
  IEnumMedia **pVal
);

Parameters

pVal
[out] Pointer to the IEnumMedia interface for the desired item.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

This method is interchangeable with get__NewEnum except that it returns IEnumMedia instead of IUnknown.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMediaCollection


ITMediaCollection::get_Item

The get_Item method gets an ITMedia pointer corresponding to the specified index.

HRESULT get_Item(
  LONG Index,
  ITMedia **pVal
);

Parameters

Index
[in] Index of media item to get.
pVal
[out] Pointer to the ITMedia interface for the desired item.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_INVALIDARG | The Index parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

Most C and C++ lists are 0-based, but this index is 1-based for Visual Basic compatibility, meaning the first item has an index number of 1.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMediaCollection


ITMediaCollection::get__NewEnum

The get__NewEnum method returns an enumerator for the collection.

HRESULT get__NewEnum(
  IUnknown **pVal
);

Parameters

pVal
[out] Pointer to an IUnknown interface on an enumerator object for the collection.

Call the QueryInterface method on the returned IUnknown interface to obtain a pointer to an IEnumVARIANT enumeration interface on the collection. IEnumVARIANT provides a number of methods that you can use to iterate through the collection.

For more information, see the following Remarks section.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

This method is interchangeable with get_EnumerationIf except that it returns IUnknown instead of IEnumMedia.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMediaCollection


ITMediaCollection::Create

The Create method creates a new media with default properties, adds it to the collection at the specified index, and returns a pointer to the ITMedia interface.

HRESULT Create(
  LONG Index,
  ITMedia **ppMedia
);

Parameters

Index
[in] Index for the new item. The minimum value for the index is 1, and the maximum value for the index is the current number of items + 1.
ppMedia
[out] Pointer to ITMedia interface created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppMedia parameter is not a valid pointer.
E_INVALIDARG | The Index parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

Most C and C++ lists are 0-based, but this index is 1-based for Visual Basic compatibility, meaning the first item has an index number of 1.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMediaCollection


ITMediaCollection::Delete

The Delete method deletes the media corresponding to the specified index.

HRESULT Delete(
  LONG Index
);

Parameters

Index
[in] Index of media to be deleted.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Index parameter has a value less than 1 or greater than the current number of elements.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Internal error (should only occur if a previous call returned an error).
E_NOTIMPL | This method is not yet implemented.
HRESULT_FROM_ERROR_CODE(SDPBLB_CONF_BLOB_DESTROYED) | The SDP blob doesn't exist.

Remarks

Most C and C++ lists are 0-based, but this index is 1-based for Visual Basic compatibility, meaning the first item has an index number of 1.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITMediaCollection


ITRendezvous

The ITRendezvous interface is the main interface for the Rendezvous control. An application calls the COM CoCreateInstance function on this interface to create the Rendezvous object.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITRendezvous methods | Description
get_DefaultDirectories | Gets the default directories configured by the system administrator. Similar to EnumerateDefaultDirectories but used by Visual Basic and other scripting languages.
EnumerateDefaultDirectories | Enumerates default directories.
CreateDirectory | Creates a directory of given type and name.
CreateDirectoryObject | Creates a new directory object.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.


ITRendezvous::get_DefaultDirectories

The get_DefaultDirectories method enumerates all configured default directories. This method is similar to EnumerateDefaultDirectories but is provided for use by Visual Basic and other scripting languages.

HRESULT get_DefaultDirectories(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to a VARIANT that will receive an ITCollection of ITDirectory interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to create a collection.
E_POINTER | Pointer is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITRendezvous, ITCollection, ITDirectory


ITRendezvous::EnumerateDefaultDirectories

The EnumerateDefaultDirectories method enumerates all configured default directories. This method is similar to get_DefaultDirectories but is designed for C/C++.

HRESULT EnumerateDefaultDirectories(
  IEnumDirectory **ppEnumDirectory
);

Parameters

ppEnumDirectory
[out] Pointer to receive IEnumDirectory enumerator listing default directories.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | Pointer is invalid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITRendezvous


ITRendezvous::CreateDirectory

The CreateDirectory method creates an ITDirectory object corresponding to a directory of the given type and name.

HRESULT CreateDirectory(
  DIRECTORY_TYPE DirectoryType,
  BSTR pName,
  ITDirectory **ppDir
);

Parameters

DirectoryType
[in] The type of the directory. See DIRECTORY_TYPE.
pName
[in] Pointer to a BSTR containing the name of the directory to be created.
ppDir
[out] Pointer to receive an ITDirectory object of the type specified above.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pname or ppDir parameter is an invalid pointer.
E_INVALIDARG | The DirectoryType parameter is not valid.

Remarks

For directories of type DT_NTDS, pName is ignored because Rendezvous supports using only the local domain controller (DC).

The application must use SysAllocString to allocate memory for the pName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITRendezvous, DIRECTORY_TYPE


ITRendezvous::CreateDirectoryObject

The CreateDirectoryObject method creates a new ITDirectoryObject object.

HRESULT CreateDirectoryObject(
  DIRECTORY_OBJECT_TYPE DirectoryObjectType,
  BSTR pName,
  ITDirectoryObject **ppDirectoryObject
);

Parameters

DirectoryObjectType
[in] The type of the object. See DIRECTORY_OBJECT_TYPE.
pName
[in] Pointer to a BSTR containing the name of the object.
ppDirectoryObject
[out] Pointer to receive the interface pointer for the newly created ITDirectoryObject object.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The DirectoryObjectType parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | Pointer is invalid.

Remarks

The application must use SysAllocString to allocate memory for the pName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.
Library: Use Rendid.lib.

See Also

ITRendezvous, DIRECTORY_OBJECT_TYPE


ITSdp

The ITSdp interface provides methods for the manipulation of a Session Descriptor Protocol (SDP, see RFC 2327) conference blob component. It provides the following functionality:

  • Provides access to some of the properties that are common to all the media. These include attributes pertaining to the creator's personal information, session description, and address type information.
  • Provides the starting point for accessing the time and media collections through properties.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITSdp methods | Description
get_IsValid | Validates the SDP blob for structure and field values.
get_ProtocolVersion | Gets the SDP protocol version.
get_SessionId | Gets the 32bit NTP (Network Time Protocol) value that serves as the session identifier.
get_SessionVersion | Gets the 32bit (ideally NTP) value that serves as the session version.
put_SessionVersion | Sets session version.
get_MachineAddress | Gets the machine address of the originating host.
put_MachineAddress | Sets the machine address of the originating host.
get_Name | Gets the session name.
put_Name | Sets the session name.
get_Description | Gets the session description.
put_Description | Sets the session description.
get_Url | Gets the URL.
put_Url | Sets the URL.
GetEmailNames | Gets array of e-mail names and addresses associated with conference blob.
SetEmailNames | Sets array of email names and addresses associated with conference blob.
GetPhoneNumbers | Gets the phone numbers.
SetPhoneNumbers | Sets the phone numbers.
get_Originator | Gets conference originator.
put_Originator | Gets conference originator.
get_MediaCollection | Gets pointer to ITMediaCollection interface for conference.
get_TimeCollection | Gets pointer to ITTimeCollection interface for conference.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


ITSdp::get_IsValid

The get_IsValid method validates the Session Descriptor Protocol (SDP; see RFC 2327) blob for structure and field values.

HRESULT get_IsValid(
  VARIANT_BOOL *pfIsValid
);

Parameters

pfIsValid
[out] Indicates whether the blob structure is valid.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pfIsValid parameter is not valid.
E_POINTER | The pfIsValid parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp


ITSdp::get_ProtocolVersion

The get_ProtocolVersion method gets the Session Descriptor Protocol (SDP; see RFC 2327) protocol version.

HRESULT get_ProtocolVersion(
  unsigned char *pProtocolVersion
);

Parameters

pProtocolVersion
[out] Pointer to the protocol version.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pProtocolVersion parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp


ITSdp::get_SessionId

The get_SessionId method gets the 32-bit NTP (Network Time Protocol) value that serves as the session identifier. This is generated automatically when the session is created.

HRESULT get_SessionId(
  DOUBLE *pSessionId
);

Parameters

pSessionId
[out] Pointer to the session identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pSessionId parameter is not valid.
E_POINTER | The pSessionId parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The return value of this method could be ULONG, but Visual Basic doesn't support the ULONG type. A DOUBLE is the next smallest type that encompasses the entire range of values required.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp


ITSdp::get_SessionVersion

The get_SessionVersion method gets the 32-bit (ideally Network Time Protocol, or NTP) value that serves as the session version. Although this is generated automatically when the session is created, the user is responsible for changing it when the SDP is modified.

HRESULT get_SessionVersion(
  DOUBLE *pSessionVersion
);

Parameters

pSessionVersion
[out] Pointer to the session version identifier.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pSessionVersion parameter is not valid.
E_POINTER | The pSessionVersion parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The return value of this method could be ULONG, but Visual Basic doesn't support the ULONG type. A DOUBLE is the next smallest type that encompasses the entire range of values required.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::put_SessionVersion


ITSdp::get_MachineAddress

The get_MachineAddress method gets the machine address of the originating host.

HRESULT get_MachineAddress(
  BSTR *ppMachineAddress
);

Parameters

ppMachineAddress
[out] Pointer to a BSTR containing the machine address of the conference host.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppMachineAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppMachineAddress parameter.

The ppMachineAddress parameter can be returned as either a DNS name ("JohnSmith.workinghard.microsoft.com") or an IP address ("10.111.222.111").

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::put_MachineAddress


ITSdp::GetPhoneNumbers

The GetPhoneNumbers method gets an array of phone numbers associated with a conference blob.

HRESULT GetPhoneNumbers(
  VARIANT *pNumbers,
  VARIANT *pNames
);

Parameters

pNumbers
[out] VARIANT pointer to a SAFEARRAY of BSTRs listing phone numbers.
pNames
[out] VARIANT pointer to a SAFEARRAY of BSTRs listing names.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pNumbers or pNames parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The lists that pNumbers and pNames point to are the same length.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp


ITSdp::SetPhoneNumbers

The SetPhoneNumbers method sets an array of phone numbers associated with a conference blob.

HRESULT SetPhoneNumbers(
  VARIANT Numbers,
  VARIANT Names
);

Parameters

Numbers
[in] SAFEARRAY of BSTRs listing phone numbers.
Names
[in] SAFEARRAY of BSTRs listing names.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Numbers or Names parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The lists that Numbers and Names point to are the same length.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp


ITSdp::get_Name

The get_Name method gets the session name. This has to be an ASCII convertible string if the character set is ASCII. (Otherwise, it can be any BSTR string.)

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to a BSTR containing the session name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::put_Name


ITSdp::get_Description

The get_Description method gets the session description (BSTR). This has to be an ASCII convertible string if the character set is ASCII. (Otherwise, it can be any BSTR string.)

HRESULT get_Description(
  BSTR *ppDescription
);

Parameters

ppDescription
[out] Pointer to a BSTR containing the session description.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppDescription parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the ppDescription parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::put_Description


ITSdp::get_Url

The get_Url method gets the URL.

HRESULT get_Url(
  BSTR *ppUrl
);

Parameters

ppUrl
[out] Pointer to a BSTR representation of the URL.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppUrl parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppUrl parameter.

An URL is typically used to reference a Web page containing additional resources or background information about a conference.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::put_Url


ITSdp::put_SessionVersion

The put_SessionVersion method sets the session version.

HRESULT put_SessionVersion(
  DOUBLE SessionVersion
);

Parameters

SessionVersion
[in] Session version value.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The SessionVersion parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The return value of this method could be ULONG, but Visual Basic doesn't support the ULONG type. A DOUBLE is the next smallest type that encompasses the entire range of values required.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::get_SessionVersion


ITSdp::get_MediaCollection

The get_MediaCollection method gets a pointer to the ITMediaCollection interface for the conference.

HRESULT get_MediaCollection(
  ITMediaCollection **ppMediaCollection
);

Parameters

ppMediaCollection
[out] Pointer to ITMediaCollection.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppMediaCollection parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
HRESULT_FROM_ERROR_CODE(ERROR_INVALID_DATA) | An internal error has occurred, usually due to the failure of a previous method.
E_NOTIMPL | This method is not yet implemented.

Remarks

An ITMediaCollection pointer could also be obtained using QueryInterface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITMediaCollection


ITSdp::get_TimeCollection

The get_TimeCollection method gets a pointer to an ITTimeCollection interface for conference.

HRESULT get_TimeCollection(
  ITTimeCollection **ppTimeCollection
);

Parameters

ppTimeCollection
[out] Pointer to ITTimeCollection.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The ppTimeCollection parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
HRESULT_FROM_ERROR_CODE(ERROR_INVALID_DATA) | An internal error has occurred, usually due to the failure of a previous method.
E_NOTIMPL | This method is not yet implemented.

Remarks

An ITTimeCollection pointer could also be obtained using QueryInterface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITTimeCollection


ITSdp::put_MachineAddress

The put_MachineAddress method sets the machine address of the originating host.

HRESULT put_MachineAddress(
  BSTR pMachineAddress
);

Parameters

pMachineAddress
[in] Pointer to a BSTR containing the machine address of the conference host.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pMachineAddress parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pMachineAddress parameter and use SysFreeString to free the memory when the variable is no longer needed.

The pMachineAddress parameter can be either a DNS name ("JohnSmith.workinghard.microsoft.com") or an IP address ("10.111.222.111").

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::get_MachineAddress


ITSdp::put_Name

The put_Name method sets the session name.

HRESULT put_Name(
  BSTR pName
);

Parameters

pName
[in] Pointer to a BSTR containing the session name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pName parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::get_Name


ITSdp::put_Description

The put_Description method sets the session description.

HRESULT put_Description(
  BSTR pDescription
);

Parameters

pDescription
[in] Pointer to a BSTR containing the session description.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDescription parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pDescription parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::get_Description


ITSdp::get_Originator

The get_Originator method gets the conference originator.

HRESULT get_Originator(
  BSTR *ppOriginator
);

Parameters

ppOriginator
[out, retval] Pointer to a BSTR representation of the conference originator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppOriginator parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysFreeString to free the memory allocated for the ppOriginator parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::put_Originator


ITSdp::put_Originator

The put_Originator method sets the conference originator.

HRESULT put_Originator(
  BSTR pOriginator
);

Parameters

pOriginator
[in] Pointer to a BSTR representation of the conference originator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pOriginator parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pOriginator parameter and use SysFreeString to free the memory when the variable is no longer needed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::get_Originator


ITSdp::put_Url

The put_Url method sets the URL.

HRESULT put_Url(
  BSTR pUrl
);

Parameters

pUrl
[in] Pointer to a BSTR representation of the URL.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pUrl parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The application must use SysAllocString to allocate memory for the pUrl parameter and use SysFreeString to free the memory when the variable is no longer needed.

An URL is typically used to reference a Web page containing additional resources or background information about a conference.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp, ITSdp::get_Url


ITSdp::GetEmailNames

The GetEmailNames method gets an array of e-mail names associated with the conference blob.

HRESULT GetEmailNames(
  VARIANT *pAddresses,
  VARIANT *pNames
);

Parameters

pAddresses
[out] VARIANT pointer to a SAFEARRAY of BSTRs listing e-mail addresses.
pNames
[out] VARIANT pointer to a SAFEARRAY of BSTRs listing names.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pAddresses or pNames parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The lists that pAddresses and pNames point to are the same length.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp


ITSdp::SetEmailNames

The SetEmailNames method sets an array of e-mail addresses associated with the conference blob.

HRESULT SetEmailNames(
  VARIANT Addresses,
  VARIANT Names
);

Parameters

Addresses
[in] SAFEARRAY of BSTRs listing e-mail addresses.
Names
[in] SAFEARRAY of BSTRs listing names.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Addresses or Names parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

The lists that Addresses and Names point to are the same length.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITSdp


ITTime

The ITTime interface is a provider-specific interface for a Session Descriptor Protocol (SDP) conference blob object. It provides access to a set of activation times for the session.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTime methods | Description
get_StartTime | Gets the 32-bit NTP (Network Time Protocol) starting time value.
put_StartTime | Sets the 32-bit NTP starting time value.
get_StopTime | Gets the NTP ending time value.
put_StopTime | Sets the NTP ending time value.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


ITTime::get_StartTime

The get_StartTime method gets the 32-bit NTP (Network Time Protocol) starting time value. The session is considered active from this time.

HRESULT get_StartTime(
  DOUBLE *pTime
);

Parameters

pTime
[out] Pointer to the start time for the session.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTime parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTime, ITTime::put_StartTime


ITTime::get_StopTime

The get_StopTime method gets the NTP (Network Time Protocol) ending time value. If the end time is zero, the session is not bounded.

HRESULT get_StopTime(
  DOUBLE *pTime
);

Parameters

pTime
[out] Pointer to the stop time for the session.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTime parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTime, ITTime::put_StopTime


ITTime::put_StartTime

The put_StartTime method sets the 32-bit NTP (Network Time Protocol) starting time value. The session is considered active from this time.

HRESULT put_StartTime(
  DOUBLE Time
);

Parameters

Time
[in] Start time for the session.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Time parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTime, ITTime::get_StartTime


ITTime::put_StopTime

The put_StopTime method sets the NTP (Network Time Protocol) ending time value. If the end time is zero, the session is not bounded.

HRESULT put_StopTime(
  DOUBLE Time
);

Parameters

Time
[in] Stop time for the session.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Time parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTime, ITTime::get_StopTime


ITTimeCollection

The ITTimeCollection interface is a provider-specific interface for the Session Descriptor Protocol (SDP) conference blob object. This interface allows access to ITTime interfaces by index, and also enable the creation and deletion of time components.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTimeCollection methods | Description
get_Count | Gets number of items in collection.
get_Item | Given an index, returns an item in the collection.
get__NewEnum | Returns an enumerator for the collection.
get_EnumerationIf | Returns the IEnumTime enumeration interface that enumerates ITTime.
Create | Creates an ITTime component.
Delete | Deletes an ITTime component.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.


ITTimeCollection::get_Count

The get_Count method gets the number of items in the collection.

HRESULT get_Count(
  LONG *pVal
);

Parameters

pVal
[out] Pointer to the number of items in the collection.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTimeCollection, ITTime


ITTimeCollection::get_EnumerationIf

The get_EnumerationIf method returns the IEnumTime enumeration interface that enumerates ITTime.

HRESULT get_EnumerationIf(
  IEnumTime **pVal
);

Parameters

pVal
[out] Pointer to the IEnumTime interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

This method is interchangeable with get__NewEnum except that it returns IEnumTime instead of IUnknown.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTimeCollection, ITTime


ITTimeCollection::get_Item

The get_Item method gets an item from the collection using an index.

HRESULT get_Item(
  LONG Index,
  ITTime **pVal
);

Parameters

Index
[in] Index of the item to get.
pVal
[out] Pointer to ITTime desired interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_INVALIDARG | The Index parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTimeCollection, ITTime


ITTimeCollection::get__NewEnum

The get__NewEnum method returns an enumerator for the collection.

HRESULT get__NewEnum(
  IUnknown **pVal
);

Parameters

pVal
[out] Pointer to an IUnknown interface on an enumerator object for the collection.

Call the QueryInterface method on the returned IUnknown interface to obtain a pointer to an IEnumVARIANT enumeration interface on the collection. IEnumVARIANT provides a number of methods that you can use to iterate through the collection.

For more information, see the following Remarks section.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Remarks

This method is interchangeable with get_EnumerationIf except that it returns IUnknown instead of IEnumTime.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTimeCollection, ITTime


ITTimeCollection::Create

The Create method creates a new ITTime component.

HRESULT Create(
  LONG Index,
  ITTime **ppTime
);

Parameters

Index
[in] Index of the item to create. (The index array is one-based.)
ppTime
[out] Pointer to the ITTime component created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTime parameter is not a valid pointer.
E_INVALIDARG | The Index parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTimeCollection, ITTime


ITTimeCollection::Delete

The Delete method deletes an ITTime component.

HRESULT Delete(
  LONG Index
);

Parameters

Index
[in] Index of the ITTime component to be deleted. (The index array is one-based.)

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The Index parameter is not valid.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_FAIL | Unspecified error.
E_NOTIMPL | This method is not yet implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.
Library: Use Sdpblbid.lib.

See Also

ITTimeCollection, ITTime


Rendezvous Enumerations

Rendezvous methods use the following enums to set and report on events and states.

BLOB_CHARACTER_SET

DIRECTORY_TYPE

DIRECTORY_OBJECT_TYPE

RND_ADVERTISING_SCOPE


BLOB_CHARACTER_SET

The BLOB_CHARACTER_SET enum indicates the character set used by the current conference blob.

typedef enum BLOB_CHARACTER_SET
{
  BCS_ASCII   = 1,
  BCS_UTF7    = 2,
  BCS_UTF8    = 3
} BLOB_CHARACTER_SET;

Members

BCS_ASCII
Standard ASCII format.
BCS_UTF7
Seven-bit transformation format of Unicode. For details on this format, conduct an Internet search for RFC 1642.
BCS_UTF8
UCS Transformation Format 8. For details on this format, conduct an Internet search for ISO (the International Organization for Standardization) and IEC (the International Electrotechnical Commission) document ISO/IEC JTC1/SC2/WG2 N 1036, dated August 1, 1994, by WG2 Project Editor.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Sdpblb.h.

See Also

ITDirectoryObjectConference, get_CharacterSet, Init, SetConferenceBlob


DIRECTORY_OBJECT_TYPE

The DIRECTORY_OBJECT_TYPE enum is a descriptor of whether a directory object is a conference or a user.

typedef enum DIRECTORY_OBJECT_TYPE
{
  OT_CONFERENCE  = 1,
  OT_USER        = 2

} DIRECTORY_OBJECT_TYPE;

Members

OT_CONFERENCE
Conference.
OT_USER
User.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.

See Also

ITDirectory, ITDirectoryObject, get_DirectoryObjects, EnumerateDirectoryObjects, get_ObjectType, CreateDirectoryObject


DIRECTORY_TYPE

The DIRECTORY_TYPE enum is used to indicate the type of directory server.

typedef enum DIRECTORY_TYPE
{
  DT_NTDS   = 1,
  DT_ILS    = 2

} DIRECTORY_TYPE;

Members

DT_NTDS
Directory type is NTDS.
DT_ILS
Directory type is ILS. The ILS directory type is valid only for Windows 2000 and not for Whistler.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.

See Also

ITDirectory, get_DirectoryType, ITRendezvous, CreateDirectory


RND_ADVERTISING_SCOPE

Members of the RND_ADVERTISING_SCOPE enumeration specify how widely a conference announcement is distributed. Values correspond to the advertising scope property on the ITDirectoryObjectConference interface.

typedef enum RND_ADVERTISING_SCOPE
{
  RAS_LOCAL   = 1,
  RAS_SITE    = 2,
  RAS_REGION  = 3,
  RAS_WORLD   = 4
} RND_ADVERTISING_SCOPE;

Members

RAS_LOCAL
Advertising scope is local.
RAS_SITE
Advertising scope is site.
RAS_REGION
Advertising scope is region.
RAS_WORLD
Advertising scope is the world.

Mapping between scope string value, enum value, and time to live (TTL) based on SDP Internet draft.

Scope string value | RND_ADVERTISING_SCOPE | TTL
Local | AS_LOCAL | 1
Site | AS_SITE | 15
Region | AS_REGION | 63
World | AS_WORLD | 127

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.

See Also

ITDirectoryObjectConference, get_AdvertisingScope, put_AdvertisingScope


Rendezvous Constants

The followings constants are used by Rendezvous methods.

RENDBIND

RND Error Returns


RENDBIND_ Constants

The RENDBIND constants are flags used by the ITDirectory::Bind method to indicate types of authentication supplied.

RENDBIND_AUTHENTICATE 0x00000001
Authenticate user.
RENDBIND_DEFAULTDOMAINNAME 0x00000002
Use default domain name.
RENDBIND_DEFAULTUSERNAME 0x00000004
Use default user name.
RENDBIND_DEFAULTPASSWORD 0x00000008
Use default password.
RENDBIND_DEFAULTCREDENTIALS 0x0000000e
The previous three or'ed together for convenience.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rend.h.

See Also

ITDirectory, ITDirectory::Bind


RND_ Constants

The following constants may be returned as errors.

RND_INVALID_TIME 0xe0000200
The time value entered is not valid.
RND_NULL_SERVER_NAME 0xe0000201
The server name is NULL, probably because ITConferenceBlob::Init has not been run or did not succeed.
RND_ALREADY_CONNECTED 0xe0000202
The ITDirectory::Connect method was called, but a connection already exists.
RND_NOT_CONNECTED 0xe0000203
The ITDirectory::Connect method has not been called, or failed.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Rnderr.h.


TAPI Service Provider Overview

TAPI service providers are an abstraction layer between TAPI applications and the underlying hardware and transport protocols. A Telephony Service Provider (TSP) supplies call controls and a Media Service Provider (MSP) supplies detailed control over the media of a call. A TSP/MSP pair can implement the capabilities needed for applications ranging from basic telephony to IP multicast multimedia conferencing.

TAPI applications reside in their own process space. TAPI applications load the Tapi32.dll or Tapi3.dll into their process, and TAPI communicates with Tapisrv.exe through a private RPC interface. A TSP runs in the context of TAPISRV. A given TSP may reside on a machine other than the user's machine and is accessed using a remote TSP. Tapisrv.exe is implemented as a service process within SVCHOST. An MSP lives within the process space of the application and is always local.

A TSP/MSP pair can be regarded as having a virtual private communication path. Information can be sent between the two using opaque buffers that are not interpreted by either TAPISRV or the TAPI DLL.

Some service providers implement operations specific to the hardware involved. TAPI 2.x provides access to such operations through the lineDevSpecific or phoneDevSpecific function. TAPI 3.x exposes provider-specific Interfaces.

The following diagram illustrates the flow of controls and information, showing one stand-alone TSP (Unimodem) and one TSP/MSP pair (H.323).


Call Scenario Using A TSP/MSP Pair

The following diagram illustrates the progress of an incoming call that involves both a TSP and an MSP.

Incoming Call Setup

  1. The TSP sends a LINE_NEWCALL message to TAPISRV. The call state is LINECALLSTATE_OFFERING.
  2. TAPISRV notifies clients of the call.
  3. TAPI3 creates the TAPI Call object, then calls ITMSPAddress::CreateMSPCall, which is implemented by the MSP.
  4. The MSP creates an MSP Call object and default streams based on the media types required for the call. It returns an IUnknown pointer to the MSP call object.
  5. TAPI3 aggregates the MSP Call object into the TAPI Call object, making interfaces such as ITStreamControl available to the application. It then notifies the application of the new call.

The application may then use methods such as ITStream::SelectTerminal to complete preparations for call completion.

Incoming Call Completion

  • The application calls ITBasicCallControl::Answer.
  • TAPI3 calls lineAnswer.
  • TAPISERV calls TSPI_lineAnswer.
  • The TSP initiates call streaming. Usually, the TSP sends a message to the corresponding MSP, and the MSP starts the streams. In some TSP/MSP implementations, the TSP starts the streams.

TSP/MSP Communication During Call Progress

Once the call is in progress, the TSP and the MSP communicate by passing opaque buffers through TAPISRV and TAPI3.

  • The TSP sends information to the MSP by sending the LINE_SENDMSPDATA message to TAPISRV.
  • The MSP receives information from the TSP through the ITMSPAddress:: ReceiveTSPData method. If the data is related to a MSP call object, an interface pointer to the MSP call object is provided as a parameter of that method.
  • The MSP sends information to the TSP by sending a MSP_TSP_DATA event to TAPI 3.0.
  • The TSP receives information from the MSP through the TSPI_lineReceiveMSPData function.

The exact process and content of communication between service providers is specific to a given TSP/MSP set.

Note For outgoing calls, the MSP typically knows about the call before the TSP. If the MSP tries to communicate with the TSP before the TSP is informed about a call, the communication will fail. When the MSP and the TSP need to exchange information concerning a specific call, the TSP should initiate communication.


About the Telephony Service Provider (TSP)

A TAPI telephony service provider (TSP) is a dynamic-link library (DLL) that supports communications device control through a set of exported service functions. A TAPI application uses standardized commands, TAPI passes information to the telephony service provider, and the TSP handles the specific commands that must be exchanged with the device.

The sections immediately following this topic briefly describe the TSPs provided with Microsoft® Windows® operating systems. For detailed information, please see the Resource Kit for the target operating system. Third-party TSPs for specialized communications devices will typically be provided by the manufacturer and will be installed with the device.

Telephony Service Provider Interface (TSPI) is an overview on creating a TSP that will function properly within the Microsoft Telephony environment. TSPI Reference documents the specific programming elements involved.

Media service providers (MSPs) have been added starting with the Windows 2000 release. An MSP implements detailed control of media streaming. See About The Media Service Provider (MSP) for information on MSP functionality.


H323 TSP

The H323 TSP (H323.tsp), when paired with the H323 MSP (H323msp.dll), allows an application to make and receive video and audio calls using the H.323 protocol for IP telephony.

This TSP supports address type values of LINEADDRESSTYPE_PHONENUMBER, LINEADDRESSTYPE_IPADDRESS, LINEADDRESSTYPE_EMAILNAME, and LINEADDRESSTYPE_DOMAINNAME.

The H323 MSP has been enhanced in Windows 2000 SP1 to enable H323-SDP bridge terminals.

The H323 TSP is installed with Windows 2000.


IPConf TSP

The IPConf TSP (Ipconf.tsp), when paired with the IPConf MSP (Confmsp.dll), provides conferencing access to Internet Protocol networks, such as the Internet and many corporate intranets.

This TSP supports an address type value of LINEADDRESSTYPE_SDP.

The IPConf MSP has been enhanced in Windows 2000 SP1 to enable H323-SDP bridge terminals.

The IPConf TSP is installed with Windows 2000.


Kernel-Mode Device Driver TSP

The Kernel-mode TSP (Kmddsp.tsp) allows an application to handle legacy WAN miniports (for example, NDIS 4.0 drivers) as TAPI devices.

The Kernel-mode TSP is installed with Windows NT, Windows 95, Windows 98, and Windows 2000.


NDIS Proxy TSP

The NDIS Proxy is a kernel-mode component that exposes NDIS miniports as TAPI lines. The NDIS Proxy TSP (Ndptsp.tsp) allows TAPI to communicate with the NDIS Proxy.

The NDIS Proxy TSP is installed with Windows NT, Windows 95, Windows 98, and Windows 2000.


Remote TSP

The Remote TSP (Remotesp.tsp) provides access to communications resources not local to the current machine, such as a company's modem pool. Once the Remote TSP is configured to point at a given server, resources appear to a local application as if they existed directly on the user's machine.

Tcmsetup is a command-line utility that allows configuration of a Remote TSP. Please see Windows Help or the Resource Kit for information on this utility.

The Remote TSP is installed with Windows NT, Windows 95, Windows 98, and Windows 2000.


Third-Party TSP

Specialized communications hardware such as cable modems or telephony cards typically arrive with one or more TSPs and MSPs specific to the device. Documentation for the device should indicate capabilities and give programming guidelines.

If a legacy TSP does not have an MSP but does use wave devices, TAPI will associate the Wave MSP with that TSP. Legacy TSPs that do not use wave devices will not be assigned an associated MSP, and stream control operations will not be available.

A third-party TSP is installed with the device it is intended to support.


Unimodem TSP

The Unimodem, or Universal Modem Driver, TSP (Unimdm.tsp) provides access to nearly all standard modems. The versions on Windows 95, Windows 98, and Windows 2000 support voice modems that allow half-duplex streaming. They are supported by the Wave MSP and stream control is possible. Unimodem on Windows NT 4.0 or less does not support voice modems, so direct stream control is not possible .

This TSP supports an address type value of LINEADDRESSTYPE_PHONENUMBER. If the programmer wants to use the dialing rules, the TAPI 3 ITAddressTranslation interface or the TAPI 2 lineTranslateAddress function must be used to obtain a dialable string from a phone number in canonical format.

The Unimodem TSP is installed with Windows NT, Windows 95, Windows 98, and Windows 2000.


Telephony Service Provider Interface (TSPI)

A Telephony Service Provider (TSP) handles device-specific controls for communications programming. A TSP must conform to the Telephony Service Provider Interface (TSPI) in order to function as a service provider within the Microsoft Telephony environment. TSPI defines the external functions exposed by a telephony service provider supplied with communications equipment.

A TSP author must be familiar with the material in Microsoft Telephony Overview, which covers general telephony architecture and provides an overview of material common to several telephony APIs. For example, this section contains a list of session control operations, such as Park, with descriptions of each operation and jumps to related TAPI 2.2, TAPI 3.0, and TSPI programming elements.

The following overviews cover material specific to the needs of a TSP author. Please note that the most difficult parts of writing a TSP are device-and operating-system-specific details, which are outside the scope of this document.

The TSPI overview is divided into six sections:

General Programming Considerations covers DLL requirements, proper handling of versions, error checks performed by TAPI, a summary of how TSPI functions correspond to TAPI 2.2 (TAPI/C) functions, and a discussion of levels of service as expressed in TSPI.

The Life Cycle of a Telephony Service Provider contains a high-level summary of a TSP's operational phases.

Device Access covers the basics of how a TSP exposes device information and controls to TAPI.

Session Access covers what TAPI expects of a TSP during a communications session.

Media Access provides a limited set of controls over media streams. Much finer control is possible through use of a media service provider, and service provider authors should use this API whenever feasible. The TSPI provides for communications between a TSP/MSP pair.

Phone Devices covers the supplemental information and operations exposed if a TSP handles phone set control. These operations are optional.

The Telephony Service Provider UI DLL Interface cover special functions that can be implemented to allow a user to directly set many aspects of a TSP's functionality.

Please see the TSPI Reference for details of the TSPI programming elements.


General Programming Considerations

The following considerations apply specifically to Telephony service providers (TSPs). Please also consult the main overview's General Programming Considerations section for material that covers Microsoft Telephony.

  • 32 bit operation: On Windows NT/Windows 2000 platforms, a TSP must be a 32-bit component; 16-bit service providers do not run on Windows NT/Windows 2000. On the Windows 95 and Windows 98 platforms, service providers should be 32-bit components, but existing 16-bit Windows 3.1, Windows 95, and Windows 98 service providers are supported by a 16-bit thunk layer.
  • List "Telephony Service" as a dependency: The installation program must include "Telephony Service" in the list of service names passed to the lpDependencies parameter of the CreateService function. When another service is activated by the telephony service provider during the service provider startup (during TSPI_providerEnumDevices, TSPI_lineNegotiateTSPIVersion, or TSPI_providerInit), this service must also be listed as a dependency of the "Telephony Service." Other functions that may be useful to a TSP in this position are QueryServiceConfig and ChangeServiceConfig.
  • Support TAPI Version 2.0 or above data structures: TAPI does not provide backward compatibility for TSPs supporting only data structure formats for version 1.3 or 1.4.
  • Import functions by name rather than ordinal: The performance differential, which was significant in 16-bit Windows, is very slight in 32-bit Windows and no longer justifies the relative complexity, confusion, and risk of error that is possible in requiring service providers to export TSPI functions by ordinal.
  • Fully Unicode: All strings passed as parameters to TSPI functions or returned by telephony service providers in structures or through pointers must be in Unicode.
  • Run in user mode: Kernel-mode components do not have direct access to TAPI services. Service provider developers can, of course, use any appropriate mechanism to access kernel mode components, should they choose to use such an architecture.
  • Use the registry for storage of persistent private data: This data must not be placed in TAPI's section of the registry, the format of which is not guaranteed to be maintained in future versions. Service providers should create their own branch under the Software key. Service providers should not directly access their registry parameters from within the context of an application (for example, directly from a TUISPI function), but should instead pass requests back to the main service provider DLL in the TAPISRV context for synchronization and processing.
  • Expose standard dynamic-link library entry point functions: TAPI will not be able to link in if these are not available.
  • Report events by using TAPI-supplied callback functions.
  • Run in protected mode: This requires that the PROTMODE flag must be given in the service provider module definition file (.DEF).
  • Implement and export all basic telephony operations: See TSPI Basic Telephony Functions for a summary of these operations.
  • Supplemental function implementation must not deviate from TAPI specifications: A TSP author may be tempted to slightly shift the intent of a function in order to suit a given need. This can result in unpredictable behavior on the part of applications attempting to use the TSP.
  • Use file name extension .tsp instead of DLL: Although not a strict requirement, using this extension lets users change the service configuration by using the standard telephony control panel.
  • Implement proper synchronization mechanisms on global data and resources: Because a TSP runs within the context of a Win32 process, service providers can be re-entered in the same or different functions from separate threads. For performance reasons, implementers are discouraged from requiring a single master mutex on the entire service provider, although such a mechanism can be advantageous during an interim period while porting 16-bit service provider code. TAPI provides this mutex if requested by the service provider during TSPI_providerInit. TAPI is also set up so that it does not call a telephony service provider function on the same thread the telephony service provider used to call the LINEEVENT, PHONEEVENT, or ASYNC_COMPLETION callbacks in TAPI. However, it is possible for the service provider to be entered on other threads while it is executing in a TAPI callback function.
  • If user interface elements are implemented, export the user interface DLL functions (prefixed by TUISPI): These can be included in a single DLL along with the TSPI functions.

Although TAPI grants simultaneous access by multiple applications to a single service provider, the service provider is not responsible for managing this access.

TAPI assigns a device identifier to each service provider. The set of device identifiers for all service providers is contiguous and non-overlapping.

TAPI performs some error checking before passing parameters to a service provider. See Error Checking for a description of tests that a telephony service provider does not need to replicate.


TSPI Versioning

Over time, different versions of TAPI, applications, and service providers may be produced. These new versions can make new definitions, such as for new features, new members in data structures, and new bit fields. Version numbers are therefore necessary to indicate how to interpret various data structures.

To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, Microsoft Telephony provides a simple version negotiation mechanism for applications. There are two different versions that need to be agreed on by TAPI and the telephony service provider for each line device. The first is the version number for the Basic and Supplementary Telephony SPI, referred to as the TSPI interface version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and datatypes used by TSPI's Basic and Supplementary features is defined by the TSPI version, while the extension version determines the format of data structures defined by the vendor-specific extensions.

These two types of version negotiation are handled by two different procedures: TSPI_lineNegotiateTSPIVersion is used to negotiate the TSPI interface version, and TSPI_lineNegotiateExtVersion is used to negotiate the extension version. Extension version negotiation can be skipped if extensions are not wanted. If these ranges input during negotiation overlap, the service provider must return a value within the overlapping portion of the range as the result of the negotiation. Usually, this should be the highest possible value. If the ranges do not overlap, the two parties are incompatible and the function returns an error.

Results of a negotiation simply indicate that the service provider is willing to operate at a particular version number, but do not commit the service provider to doing so. For example, TAPI can renegotiate to determine an ideal version after having negotiated a possible version. The TSPI interface version is only committed when a line is opened using TSPI_lineOpen and survives until the device is closed. The extension version is committed when the TSPI_lineSelectExtVersion function is called, and survives until the selection is canceled by selecting extension version zero.

Extension version selection can happen many times, including while an extension version is in effect. Because the service provider is committed to the extension version, its range of supported versions narrows to exactly that extension version. For example, consider a service provider that is normally compatible with extension versions 1.0 through 5.5. If version 3.0 is in effect while a caller attempts to negotiate a version within the range 1.0 to 5.5, the negotiation returns 3.0.

Because TAPI negotiates the version, you can upgrade a service provider to new versions of the interface without requiring that TAPI also be upgraded. Similarly, TAPI can be upgraded, yet still use your older service provider.


What's New for TSPI Version 3.0

TSPI 3.0 adds functions and messages to support communication with a Media Service Provider (MSP). Functions have also been added which enhance the ease of tracking conferences using the Call Hub concept.

Functions and messages that were new or changed for TSPI version 3.0 are as follows:

TSPI_lineCloseMSPInstance
TSPI_lineCreateMSPInstance
TSPI_lineGetCallHubTracking
TSPI_lineGetCallIDs
TSPI_lineMSPIdentify
TSPI_lineReceiveMSPData
TSPI_lineSetCallHubTracking

LINE_QOSINFO
LINE_SENDMSPDATA
LINE_DEVSPECIFICEX

LINEADDRCAPFLAGS_NOPSTNADDRESSTRANSLATION member of LINEADDRCAPFLAGS_ Constants

LINEERR_INVALADDRESSTYPE member of LINEERR_ Constants.


What's New for TSPI Version 2.2

TSPI Version 2.2 changes consist primarily of a number of data structures which have additional elements. The majority of these structures are defined in tapi.h, and are used by both TAPI applications and service providers as a means of passing information.

Functions and messages that were new or changed for TSPI version 2.2 are as follows:

LINE_AGENTSESSIONSTATUS
LINE_QUEUESTATUS
LINE_AGENTSTATUSEX
LINE_GROUPSTATUS
LINE_PROXYSTATUS

LINEADDRCAPFLAGS_ACDGROUP member of LINEADDRCAPFLAGS_ Constants

LINEERR_INVALAGENTSESSIONSTATE and LINEERR_DISCONNECTED members of LINEERR_ Constants.

LINEAGENTSTATEEX_ Constants
LINEAGENTSTATUSEX_ Constants
LINEAGENTSESSIONSTATE_ Constants
LINEAGENTSESSIONSTATUS_ Constants
LINEQUEUESTATUS_ Constants
LINEGROUPSTATUS_ Constants
LINEPROXYSTATUS_ Constants
LINEPROXYREQUEST_ Constants


What's New for TSPI Version 2.1

Starting with TAPI 2.1, the telephony service provider user interface DLLs can be used to manage and display dialog boxes. TAPI loads the DLL into the process of an application that invokes any of the service provider functions that can display a dialog.

Starting with TAPI 2.1, proxy request handlers can be implemented. A handler is a full telephony application that normally executes on a telephony server and provides services that are more appropriately implemented in an application than a driver.

Functions and messages that were new or changed for TSPI version 2.1 are as follows:

TSPI_lineConditionalMediaDetection
TSPI_lineDropNoOwner—obsolete
TSPI_lineDropOnClose—obsolete
TSPI_lineGetID
TSPI_lineSetCallData
TSPI_lineSetCallQualityOfService
TSPI_lineSetCallTreatment
TSPI_lineSetLineDevStatus
TSPI_phoneGetID
TSPI_providerInit
TSPI_providerShutdown

LINE_GATHERDIGITS
LINE_GENERATE
LINE_MONITORDIGITS
LINE_MONITORMEDIA
LINE_MONITORTONE
LINE_REMOVE
PHONE_REMOVE

The Telephony service provider user interface DLL provides a means of allowing user interaction within the context of the application rather than the service provider itself. TSPI version 2.1 delivered the following new functions, messages, and structures for implementation:

TSPI_providerFreeDialogInstance
TSPI_providerGenericDialogData
TSPI_providerUIIdentify
TUISPI_lineConfigDialog
TUISPI_lineConfigDialogEdit
TUISPI_phoneConfigDialog
TUISPI_providerConfig
TUISPI_providerGenericDialog
TUISPI_providerGenericDialogData
TUISPI_providerInstall
TUISPI_providerRemove
TUISPIDLLCALLBACK
LINE_CREATEDIALOGINSTANCE
LINE_SENDDIALOGINSTANCEDATA
TUISPICREATEDIALOGINSTANCEPARAMS


Error Checking

At the TAPI level, an application can pass a variety of different parameters, many of which may be invalid. TAPI checks for bad parameters and returns errors to the application without calling the service provider. Each function description at the TSPI level describes the parameter errors that have already been tested. The service provider does not have to repeat these tests, though it must perform any additional validity tests appropriate to the function. Titles and descriptions of common parameter validity tests that appear in many functions are listed below.

Validity test | Description
Pointer validity | TAPI has already tested pointers to data storage to make sure that they point to readable or writeable memory of the size appropriate to the operation. In addition, for variably sized data structures starting with a dwTotalSize member, the data structure has been verified to ensure that the indicated total size is really available.
Fixed size validity | For variably sized data structures, the data structure has been checked to make sure that there is at least enough space for the fixed size part of the data structure and that dwTotalSize is sufficient to cover the fixed part.
Offset/size zeroed | For variably sized data structures, the "...Offset" and "...Size" fields corresponding to parts that the service provider fills in have been preset with zero values before the service provider was called.
Handle validity | TAPI guarantees that line, phone, and call handles (of defined types HDRVLINE, HDRVPHONE, and HDRVCALL) are valid. That is, they are values that have been returned without error as handles in TSPI_lineOpen, TSPI_phoneOpen, or one of the following that starts the lifetime of a call handle: TSPI_lineMakeCall TSPI_lineCompleteTransfer TSPI_lineForward TSPI_linePickup TSPI_linePrepareAddToConference TSPI_lineSetupConference TSPI_lineSetupTransfer TSPI_lineUnpark LINE_NEWCALL messages


Overall Comparison with TAPI

The TSPI specification is very closely related to the specifications for TAPI 2.2 (TAPI/C). Most of the functions in one have a corresponding function in the other. The usual correspondence is as follows:

  • TSPI functions have the same names as TAPI functions except that they are prepended with "TSPI_". For example, the TAPI function lineAccept corresponds to the TSPI function TSPI_lineAccept.
  • Procedures that allow asynchronous operation insert a dwRequestID parameter of type DRV_REQUESTID as their first parameter. This parameter specifies the value to be returned to indicate asynchronous operation and to report asynchronous completion.
  • hCall parameters of type HCALL are replaced with hdCall parameters of type HDRVCALL, indicating the service provider's handle for the call.
  • hLine parameters of type HLINE are replaced with hdLine parameters of type HDRVLINE, indicating the service provider's handle for the line.
  • hPhone parameters of type HPHONE are replaced with hdPhone parameters of type HDRVPHONE, indicating the service provider's handle for the phone.
  • Procedures that create a new call, such as TSPI_lineMakeCall, replace a single lphCall parameter with two parameters: an htCall of type HTAPICALL parameter that passes in the TAPI handle for the call, and an lphdCall of type LPHDRVCALL that indicates the location to which the service provider must write its new handle for the call. A similar split of parameters occurs in TSPI_lineOpen and TSPI_phoneOpen.
  • At the TSPI level, there is no notion of "privilege" associated with device handles. Furthermore, at the API level, each application that has a device or call handle has a different handle, but TAPI merges these into a single handle in the service provider side. As a consequence, the error codes and status messages relating to privilege and number of clients using a device do not appear at the TSPI level.

The set of TAPI functions do not map one to one onto the set of TSPI functions. In particular, functions related to privilege, phone number translation, and interapplication communication are handled by TAPI and have no corresponding function in TSPI. Other functions, such as those used for service-provider configuration and initialization, have no corresponding functions in TAPI.


TSPI Levels of Service

TAPI divides communications services into Basic, Supplemental, and Extended. Please see TAPI Levels of Service for additional information.

A TSP is required to implement all Basic Telephony functions. TSPI Basic Telephony Functions contains a summary of these functions.

Supplementary Telephony includes features found on modern PBXs, such as hold, transfer, conference, park, and so on. A service provider should provide a supplementary telephony service only if it can implement the exact meaning as defined by TAPI. If not, the feature should be provided as an Extended Telephony service. All supplementary features are optional. A service provider specifies which services it supports through responses to functions such as TSPI_lineGetDevCaps or TSPI_lineGetAddressCaps. A single supplementary service can consist of multiple function calls and messages. Phone device services are part of Supplementary Telephony.

Extended Telephony services allow a provider to implement device-specific functions. The service provider must uniquely identify the extensions by using an extension identifier. Applications retrieve and use this unique identifier to determine what extensions the service provider supports.

The extensions can apply to several manufacturers. Special functions and messages such as lineDevSpecific and phoneDevSpecific are provided in TAPI. They are used to allow the extension of the set of functions (in contrast to enumerations, bit flags, and data structure members) supported by the service provider. The parameters for each function are also defined by the service provider.

An identifier is assigned to a set of extensions (before distribution), not to each individual instance of an implementation of those extensions. The EXTIDGEN utility in TSPI generates unique extension identifiers for service providers. It uses an Ethernet-adapter address, a random number, and the time of day to generate an identifier, so it is extremely unlikely that the resulting extension identifier will conflict with any other service provider. As a result, there is no need for vendors to register extension identifiers.

The EXTIDGEN utility does not generate extension identifiers unless the computer on which it is run is also running NetBIOS or other network software.


Life Cycle of a Telephony Service Provider

This topic provides a high-level review of TSP operations.

A session is the time during which a particular configuration remains valid and telephony operations are carried out. A service provider can support many sessions between the time it is first loaded and when it is finally freed. For each session, TAPI negotiates the version of the interface, starts the session, carries out operations, and eventually shuts down the session. The service provider must not retain information from one session to the next.

After the interface version is known, TAPI calls the TSPI_providerInit function to set all operational parameters. The service provider is ensured that all of the configuration information in the registry is stable when the TSPI_providerInit function is called. Most service providers read all configuration information at that time.

Normal operations can proceed in any order, after the service provider is initialized.

TAPI negotiates device-specific information on a per-device basis. TAPI and the service provider commit to a version when a device is opened.

The service provider can receive requests to select and cancel extension versions. While an extension version is selected, the device operates strictly according to that device-specific extension version.

Negotiation of a device-specific extension version can happen multiple times, both before and after the device is opened. TAPI passes a version range, and the service provider chooses and returns a value from this range. Normally, the service provider has device-specific extensions disabled.

This commits both TAPI and the service provider to operating at that extension version level until the selection is canceled. During the time that a device-specific extension is in effect, an attempt to negotiate an extension version level should allow only the version level that is currently in effect. After the device-specific extension is canceled, a different version can be negotiated and selected.

Phone operations within the Open/Close pair are shown in the following illustration. Some of these operations are synchronous, others are asynchronous. If an operation completes asynchronously, another operation can be requested before the first reports completion. Thus, operations can overlap in any way. The service provider must eventually report completion for any asynchronous operation requested. Closing a phone forces outstanding asynchronous operations to complete (possibly with a "failure" indication).

The life cycle for line devices is similar to the life cycle for phones, except that lines have their own negotiation, initialization, open, and close procedures. Operations on open lines are bracketed by their own Open/Close pair. This pair is in turn bracketed between the same Initialization/Shutdown pair as the phone Open/Close.

The life cycles of calls are bracketed strictly between the Open/Close of the line that contains them. Lifetimes of calls can begin in several ways:

  • Requested from TAPI through functions such as lineMakeCall, lineSetupTransfer, or lineSetupConference.
  • Spontaneously originated in the service provider as new incoming calls, user-initiated calls on an attached telephone handset, or calls generated as a side effect of other operations such as putting an existing call on hold.

The lifetimes of distinct calls within the same line can overlap each other in any way. All calls end their lifetime at the time the TSPI function TSPI_lineCloseCall is invoked. The life cycle of several calls is shown in the following illustration:

A call can originate in TAPI as shown with the MakeCall/CloseCall pair. A call can also originate in the service provider. The service provider announces this with a LINE_NEWCALL message to a TAPI-supplied callback procedure. In such a case, TAPI returns its identifier for the call, which is included in subsequent callbacks reporting events occurring on the call. In the case of calls whose lifetime originates in TAPI, this identifier is included in the TSPI operation that creates the call.

All of the operations that start the lifetime of a call result in TAPI and service provider exchanging identifiers for the new call. In the case of TAPI originated calls, TAPI passes its identifier and receives the service provider's identifier as a return parameter. In the case where the call originates in the service provider, the service provider passes its identifier to TAPI and receives the TAPI identifier as a return parameter.

The following illustration offers a very high-level view of service provider installation, configuration, and removal; life-cycle sequences that span many sessions. The typical life-cycle for these operations can be shown with the following time line:

The typical installation and removal life cycle is shown, spanning multiple sessions. Calls to the Install and Remove procedures are strictly paired and do not overlap. Calls to the Config procedure can happen multiple times within this pair. One is typically done by the service provider as an internal side effect of the Install procedure to create line and phone entries. The Config procedure may be called at other times to alter an existing setup. The Install procedure must be done before any other TSPI function is permitted. In the ideal scenario, all sessions are strictly nested within the Install/Remove procedure pair.

The functions TSPI_providerInstall, TSPI_providerConfig, and TSPI_providerRemove interact with the service provider itself rather than with any specific device. They affect static configuration information that survives across multiple sessions and must be present for any other operation to proceed. Thus, all other operations are nested between the invocation of TSPI_providerInstall and the completion of its matching TSPI_providerRemove. These two operations typically happen very far apart, most likely in a different load of the service provider or a different boot of the machine. Calling the Config function externally is optional, because the Install procedure is required to include the Config behavior in addition to its own. The usual reason for calling it externally is to modify an existing configuration.

There is a subtlety embedded in the concept of the completion of a TSPI_providerRemove operation. It is desirable to allow the user to run the Telephony Control Panel utility supplied with the telephony service to alter service provider configurations, even when telephony operations (sessions) are in progress. Consequently, both the TSPI_providerConfig and TSPI_providerRemove specifications allow for invocation while there is an outstanding session. However, any changes to the configuration are required to be delayed until telephony operations are shut down and restarted. Thus, strictly speaking, the completion of any TSPI_providerConfig or TSPI_providerRemove operation happens outside any session. The nesting of actions is as shown in the figure, even though the procedures calls may appear in a slightly different order. It is permitted for a service provider to simply disallow Config or Remove while operations are in progress, although the user should be notified with a dialog box. A more user-friendly implementation that allows at least a subset of operations is preferred.

These Install, Config, and Remove operations all have the side effect of signaling any running telephony applications, which eventually results in them shutting down their use of the telephony service. Together, this ends all outstanding sessions for service providers. This signifies to service providers that they must read the new registry configuration when new sessions begin. Any changes that were pending due to a Config or Remove while operations were in progress then take effect.


Installation and Initialization

Installation of a new service provider is highly device- and operating-system-specific, so the details are outside the scope of this SDK. Generally speaking, the goal of installation is configuration of the service provider for the current communications environment. This usually involves registry entries and the setting of service dependencies.

Initialization of a telephony service provider starts with version negotiation. See TSPI Versioning for a discussion of version negotiation and current version.

TAPI then calls TSPI_providerInit, which passes the provider a pointer to a callback function used to report on asynchronous functions progress. The TSP returns a count of line and phone devices associated with the current device identifier.

Typically, the next step will be resource inventory, conducted by TAPI invoking TSPI_lineGetDevCaps and TSPI_lineGetAddressCaps. The service provider is expected to fill in those elements of the data structures involved that pertain to device and session capabilities it supports.

TAPI collects information from the various applications concerning event notification requirements, and instructs the TSP using TSPI_lineSetDefaultMediaDetection to indicate which media types to detect for a line and TSPI_lineSetStatusMessages to indicate which line and address events should be reported.


Device Access

The main concepts and operations for basic and supplemental device control are covered in The Microsoft Telephony Programming Model under Device Control, with the exception of Phone Devices, which is covered later in this portion of the SDK.

Please note that the operation listings in the overview mentioned in the previous paragraph specifically address TAPI 2.2 (TAPI/C) functions. These functions match to TSPI operations with a prefix of "TSPI_". For example, if a TAPI 2.2 application calls lineGetDevCaps, TAPI invokes the TSP's implementation of TSPI_lineGetDevCaps.

The following material addresses device control aspects that are specific to authoring a TSP.


Line Configurations

A line device can represent a pool of homogeneous resources (channels) that are used to establish calls. In a client computer, a TSP typically provides access to one or more line devices.

Here are some examples of how a service provider might model various configurations:

Example 1 A single POTS line in the computer-centric or phone-centric connection models. The most straightforward model is a single line device with one channel.

Example 2 A single BRI-ISDN line in the computer-centric or phone-centric connection models. The service provider has a number of options as to how it may want to model this, for example:

  • Model the BRI line as a single line device with a pool of two B channels that allows both channels to be combined for establishing 128 kbps calls.
  • Model each B-channel as a separate line device and disallow both channels to be combined into a single 128 kbps channel.
  • Model the BRI connection as two separate line devices, each drawing up to two channels from a shared pool of two B-channels.
  • Model as three line devices, one for each B-channel, and one for the combination. Clearly in the latter two models, resources may be assigned to different line devices at different times.

Example 3 In client/server systems, a pool of telephone ports attached to a server can be shared among multiple client computers over a local area network. The pool can be administered to assign a maximum number of line devices (quota) to each client workstation. It is not unusual for the sum of all quotas to exceed the total number of lines. Furthermore, a given client with a quota equal to 2 may be satisfied by using ports 1 and 2 at one time and ports 7 and 11 at a later time. The service provider for the pool can model this arrangement by giving each client workstation access to two line devices.

Suppose that the configuration of service providers for a given computer is such that this particular service provider gets a DeviceIDBase of 3. This implies that the (fixed) device identifiers for this client are 3 and 4. If the application later calls the TAPI 2 function lineGetDevCaps for device 3 and again for device 4, it should be able to assume that the device capabilities for each of these devices are constant, because that is the Win32 device model. As long as the given computer's service-provider configuration remains constant, the device identifiers that appear at the TSPI level remain constant, even if the server changes port allocations. For server-based devices that are pooled as described in Example 3, this holds only for line devices that have identical device capabilities. Of course, if the given computer's service-provider configuration is changed, such that this service provider gets a different DeviceIDBase, device identifiers change correspondingly.

Example 4 Switch-to-host link:

  • To provide personal telephony to each desktop, the service provider could model the PBX line paired with the computer as a single line device with one channel. Each client computer would have one line device available.
  • Each third-party station could be modeled as a separate line device. This enables the application to control calls on other stations. This solution requires that the application open each line it wants to manipulate or monitor, which may be fine if only a small number of lines is of interest, but may generate a lot of overhead if a large number of lines is involved.
  • The set of all third-party stations could be modeled as a single line device with one address (phone number) assigned to it per station. Only a single device is to be opened, providing monitoring and control of all addresses on the line (all stations). To originate a call on any of these stations, the application only needs to specify the station's address to the operation that makes the call. No extra open operations are required. This modeling does imply that all stations have the same line device capabilities, although their address capabilities could be different.

Note All of these examples are simply different ways that a service provider may choose to implement the mapping of line device behavior onto some physical realization.


Setting a Terminal for Phone Conversations

The user's computer may have access to multiple devices that are selectable by the user and used to conduct interactive voice conversations. First, there is the phone device itself, complete with lamps, buttons, display, ringer, and voice I/O device (handset, speakerphone, headset). The user's computer may also have a separate voice I/O device (such as a headset or a microphone/speaker combination attached to a sound card) for use with phone conversations.

TSPI enables the user to select where to route the information that the switch sends over the line, address, or call. The switch normally expects this to be one of its phone sets, and sends ring requests, lamp events (for stimulus phones), display data, and voice data as appropriate. The phone in turn sends hookswitch events, button press events (for stimulus phones), and voice data back to the switch.

The line portion of TSPI makes lamp events, display events, and ring events available, either as functional return codes to the various line operations in TSPI, or as unsolicited functional call status messages that are sent to the application callback. The service provider implementation is responsible for mapping between the functional TSPI level and the underlying stimulus or functional messages used by the telephony network. In functional telephony environments, TSPI functions are mapped to the functional protocol.

Using the TSPI_lineSetTerminal function, TAPI can control the routing of different low-level events exchanged between the switch and the station; it can also decide not to route some of these low-level events to a device. The routing of the different classes of events can be individually controlled. For example, the media stream of a call (such as voice) can be sent to any transducer device if the service provider and hardware are capable of doing so. Ring events from the switch to the phone can be mapped into a visual alert on the computer's screen or they can be routed to a phone device. Lamp events and display events can be ignored or routed to a phone device (which appears to behave as a normal phone set). Finally, button presses at a phone device may or may not be passed on to the line. In any case, this routing of low-level signals from the line does not affect the operation of TSPI's line portion, which always maps the low-level events to their functional equivalent. Applications can consult a line's device capabilities to determine the terminals it has available.

In other words, the TSPI_lineSetTerminal function specifies the terminal device to which the specified line, address events or call media stream events are routed. Separate terminals can be specified for each event class. Event classes include lamps, buttons, display, ringer, hookswitch, and media stream.


Extended Line Services

Extended line services (or device-specific line services) include all service-provider defined extensions to TSPI. TSPI defines a mechanism that enables service-provider vendors to extend the Telephony SPI using device-specific extensions. TSPI only defines the extension mechanism, and by doing so provides access to device-specific extensions, but TSPI does not define their behavior. Behavior is completely defined by the service provider.

The Telephony SPI consists of scalar and bit flag constant definitions, data structures, functions, and callback messages. Procedures are defined that enable a vendor to extend most of these as follows.

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. As most data constants are DWORDs, typically the range 0x00000000 through 0x7FFFFFFF is reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF are available for vendor-specific extensions. The assumption is that a vendor would define values that are natural extensions of the datatypes defined by TSPI.

For extensible bit flag data constants, a service-provider vendor can define new values for specified bits. As most bit flag constants are DWORDs, typically a specific number of the lower bits are reserved for common extensions while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up; vendor-specific extensions should be assigned from bit 31 down. This provides maximum flexibility in assigning bit positions to common extensions versus vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by TSPI.

Extensible data structures have a variably sized field that is reserved for device-specific use. Being variably sized, the service provider decides the amount of information and the interpretation. A vendor that defines a device-specific field is expected to make these natural extensions of the original data structure defined by TSPI.

Two functions, TSPI_lineDevSpecific and TSPI_lineDevSpecificFeature, and four related messages, LINE_DEVSPECIFIC, LINE_CALLDEVSPECIFIC, LINE_DEVSPECIFICFEATURE, and LINE_CALLDEVSPECIFICFEATURE, offer a vendor-specific extension mechanism. The TSPI_lineDevSpecific operation and associated LINE_DEVSPECIFIC and LINE_CALLDEVSPECIFIC messages allow the Tapi32.dll client application to access device-specific line, address, or call features that are unavailable in the Basic or Supplementary Telephony services. The parameter profile of the TSPI_lineDevSpecific function is generic in that little interpretation of the parameters is made by TSPI. Device-handle parameters have TSPI-defined meanings and are translated appropriately between the application and the service provider. Generic parameters are simply passed through unmodified. The interpretation of the generic parameters is defined by the service provider and must be understood by any applications that use them. An application that relies on device-specific extensions generally does not work with other service providers. However, applications written entirely to the Basic and Supplementary Telephony services should work with the extended service provider.

The TAPI implementation of the device-specific functions and messages is "pass-through." TAPI does not examine or modify the generic device-specific parameters and buffers, but it does map application-level opaque handle values (used at the TAPI level) to service-provider-level opaque handle values (used at the TSPI level).

Regarding handle translation, the passthrough nature of the generic parts of device-specific extensions has an imporant consequence. A service provider has no way to relate the handles used at the TSPI level to those at the TAPI level except by passing them through the predefined handle parameters and fields. Any handle put into the generic extension area is untranslated by TAPI as it is passed between application and service provider. The designer of a service-provider extension should generally not define extensions that pass handles in this way.

The appropriate approach when defining a device-specific extension that must refer to specific devices without using handles is to refer to them using their absolute device identification. The device identifier used in opening a line at the TAPI level, for example, is strictly the same value that is used at the TSPI level to open the line. Similarly, a (line device identifier, address identifier) tuple that uniquely identifies an address at the TAPI level uses the same values to identify the same thing at the TSPI level.

For convenience, a more specialized escape function is also provided. It is similar to TSPI_lineDevSpecific, but places interpretation on some of the parameters. The TSPI_lineDevSpecificFeature function and associated LINE_DEVSPECIFICFEATURE and LINE_CALLDEVSPECIFICFEATURE messages allow TAPI to emulate button presses at the line's feature phone. As feature phones and the meanings of their buttons are vendor-specific, feature invocation using TSPI_lineDevSpecificFeature is also vendor specific.

To summarize, the TSPI_lineDevSpecificFeature function is a device-specific escape function to allow sending switch features to the switch. The LINE_CALLDEVSPECIFICFEATURE message is a device-specific message sent to the application's callback as an indication of call-related features sent to the switch. LINE_DEVSPECIFICFEATURE is a device-specific message sent to the application's callback as an indication of line-related features sent to the switch.

There is no central registry for manufacturer identifiers. Instead a unique identifier generator called Extidgen.exe is made available as part of TSPI. The vendor that designs a set of device-specific extensions uses this utility to obtain a unique identifier for those extensions.


Session Access

TAPI session or call controls are those operations needed to initiate, maintain, and terminate a communications session. For basic overview information on TAPI-supported operations, please see the Session Control Overview.

To locate the appropriate TSPI function corresponding to an operation referenced there, add the prefix "TSPI_" to the TAPI 2.2 function. For example, to request that a session be parked, a TAPI 2.2 application calls linePark. TAPI will then invoke the TSP's implementation of TSPI_linePark.

When a telephony service provider informs TAPI of a new incoming call in the LINE_NEWCALL callback message, TAPI should return its handle for the call. LINE_NEWCALL can fail due to finite-resource limitations. TAPI may run out of resources to handle a new call under very high traffic conditions. In such a case, TAPI returns NULL instead of a valid call handle, indicating that the newly offered call handle was not successfully received. The service provider can respond by dropping the call or by retrying the LINE_NEWCALL after a scheduling delay. In any case, the service provider must check for this NULL return and must never attempt to pass subsequent messages using the invalid call handle.

The telephony service provider is responsible for reporting on a variety of session information. Depending on the telephony environment, not all information about a call may be available at the time the call is initially offered. For example, if caller identifier is provided by the network between the first and second ring, the caller identifier is still unknown when the call is first offered. When it becomes known shortly thereafter, a LINE_CALLINFO callback message notifies TAPI about the change in party-identifier information of the call.


Unowned Calls

To prevent unowned calls from being in the telephony system, TAPI drops calls that have been signalled up from a service provider if it cannot identify an application to be the initial owner of the call. In TAPI version 2.0 and later, TAPI calls the TSPI_lineDrop function to drop the call. In Windows 95, TAPI calls the TSPI_lineDropNoOwner function instead if the service provider exports the function.

The service provider can know in advance whether or not there is an application available to take ownership of a new call. TAPI always informs the service provider of the media types for which there is an application available by using the TSPI_lineSetDefaultMediaDetection function.

For example, if a service provider determines that there is an active call on the line having LINEMEDIAMODE_INTERACTIVEVOICE mode, it should check the default media detection before generating the LINE_NEWCALL and LINE_CALLSTATE messages. If the default media detection shows that no application is looking for a LINEMEDIAMODE_INTERACTIVEVOICE call, the service provider should not send the messages because TAPI will immediately drop it.


Call Handles

A call handle is a TSP's means of identifying a particular session. The handle is a pointer to a pointer, that is, an access to a value, a necessary piece of information, or a resource required in one variable identified in another variable. Call handles access and supply specific variable information requested by TSPI functions.


Pending Call Handles

A service provider is required to create one or more call handles (variables of type HDRVCALL) whenever TAPI calls one of these functions: TSPI_lineMakeCall, TSPI_lineCompleteTransfer, TSPI_lineForward, TSPI_linePickup, TSPI_linePrepareAddToConference, TSPI_lineSetupConference, TSPI_lineSetupTransfer, and TSPI_lineUnpark. When a service provider receives such a call, the service provider must set the variable supplied by TAPI to the value of the handle before returning from the call. TAPI considers this "pending call handle" to be tentatively valid. When the service provider actually creates the call, it must call the ASYNC_COMPLETION callback to formally validate the handle.

If TAPI calls the TSPI_lineCloseCall function before the service provider formally validates a pending call handle, the service provider must stop all further processing associated with the call handle and call the ASYNC_COMPLETION callback function using the error value LINEERR_OPERATIONFAILED.


Async Replies versus Events on New Call Handles

TSPI includes a number of operations that start the lifetime of a call handle. If the service provider returns SUCCESS for such an operation, it must fill in the opaque handle of type HDRVCALL, which it uses for the new call before it returns. TAPI never performs operations on the call before the matching ASYNC_COMPLETION has been received. If the service provider returns FAILURE, the handle automatically becomes invalid (that is, without TSPI_lineCloseCall). In effect, TAPI treats the handle as "not yet valid" until the asynchronous completion.

The service provider must also treat the handle as "not yet valid" until after the matching ASYNC_COMPLETION is received. In other words, it must not issue any LINEEVENT functions for the new call or include it in call counts in messages or status data structures for the line.

The TAPI level also conforms to these life cycle restrictions; a new call handle is not returned or valid until the matching LINE_REPLY message, and no events for the new call are delivered to the application until after the LINE_REPLY message.

The TSPI operations to which this "start lifetime" principle applies are the following:

TSPI_lineCompleteTransfer
TSPI_lineForward
TSPI_lineMakeCall
TSPI_linePickup
TSPI_linePrepareAddToConference
TSPI_lineSetupConference
TSPI_lineSetupTransfer
TSPI_lineUnpark


Call Handle Manipulation

TAPI provides a number of functions for manipulating call handles, determining the relationship among lines, calls, and address, and so on. Most of this functionality is implemented strictly within TAPI without reference to the service provider, except for TSPI_lineGetCallAddressID. This function retrieves the address identifier of an existing call within its line. Service providers that model a line as a group of address identifiers can choose an unpredictable address for a new inbound or outbound call. This function gives TAPI sufficient information to implement the lineGetNewCalls operation when it is invoked with the LINECALLSELECT_ADDRESS option.


Externally Generated Phone Numbers

A service provider can indicate externally generated phone numbers (that is, numbers for outbound calls generated externally to the computer) by setting the DisplayableAddress, CalledParty, or Comment members in the LINECALLINFO structure when processing the TSPI_lineGetCallInfo function. If TAPI has not saved its own data for these members, it leaves the data set by the service provider unchanged. If TAPI does have cached data for these members, TAPI adds its text to the end of the variable portion of the LINECALLINFO structure and overwrites the size and offset the service provider has put into the fixed portion.

A service provider can also copy an outbound number into the CalledID member. Therefore, logging applications should check the CalledID member on outbound calls if the DisplayableAddress and CalledParty members are empty.


CallHub Support

CallHub tracking is a new feature in TAPI version 3.0. CallHub functionality was added to the TAPI 2.1 family of programming elements with the delivery of Windows 2000. A CallHub represents a third-party view of a call, and TAPI's call handles represent the first-party view of a call. With CallHub tracking, the service provider is requested to follow CallHubs and give information about the call during the lifetime of a CallHub. As new parties join and leave the CallHub, the service provider should inform TAPI.

A service provider does not need to implement any new functions in order to support CallHub. It simply needs to fill in the dwCallID member of the LINECALLINFO structure. In TAPI 3.0, TAPI collects all calls with the same dwCallID and creates a CallHub handle that the application can use to track the call.


Media Access

A telephony service provider can directly supply limited access to and control over media. With the addition of media service providers, a paired MSP becomes the preferred method for accessing and manipulating media. The following material relates to media support mechanisms available through a TSP.

The media type is the form in which data is transmitted on a line. The telephony service provider is responsible for filling out the dwMediaModes member of LINEDEVCAPS, which is used by an application and by TAPI to identify the media capabilities of a given device.

The service provider is also responsible for reporting media type changes when requested. This process is sometimes referred to as call classification. The mechanism used to determine the type of a media stream (such as voice, fax, data modem) is service-provider specific.

A service provider can filter the media stream for energy or tones that characterize the media type. Alternatively, the service provider can determine the type by messages exchanged over the network, by use of distinctive ringing, or by knowledge about the caller or called ID.

If a telephony service provider supports some media control, it must accept requests to carry out actions on the media stream when given events occur, such as on receiving a specific tone or DTMF digit in the media stream. For example, the service provider might receive a request to suspend the media stream when it detects a # DTMF digit, and resume the media stream when it detects a * DTMF digit.


Monitoring

Monitoring is a service-provider defined feature that detects signals that indicate other media. For example, one application can be playing an outgoing "leave a message" voice message while the incoming call starts sending a fax "calling" tone and waits for a handshake. In order not to lose the fax call, the local application monitors for this tone while playing the voice message.

Monitoring comprises media monitoring, digit monitoring, and tone monitoring.


Media Monitoring

When a call is in the connected state, information can be transported over the call. A call's media type provides an indication of the type of information (for example, the datatype or higher-level protocol) of this media stream. TSPI allows TAPI to be provided with a callback notification about changes in a call's media type. The notification provides an indication of the call's new media type. The service provider decides how it wants to make this determination.

For example, the provider could use signal processing of the media stream to determine media type, or it could rely on distinctive ringing patterns assigned to different media streams, or on information elements passed in an out-of-band signaling protocol. Independent of how the media type is determined, TAPI is simply informed about media type changes on a call.

The media types defined by Microsoft Telephony can be found under LINEMEDIAMODE_ Constants.

Media monitoring can be enabled and disabled on a specified call with TSPI_lineMonitorMedia. TAPI specifies which media types it is interested in monitoring. If media monitoring is enabled, the detection of a media type causes TAPI to be notified in the LINE_MONITORMEDIA callback message, which notifies TAPI about a media type change. The callback provides the call handle on which the media type change was detected as well as the new media type.

There is a distinction between the media type of a call as reported by TSPI_lineGetCallInfo and the media type event reports in LINE_MONITORMEDIA messages. A call's media type is determined exclusively by TAPI and is not automatically changed by media monitoring events.

Default media type monitoring for calls is performed for the media types for which the line device has been set. This allows an inbound call's media type to be determined early based on what TAPI needs.

Note The scope of a call's media monitoring of a call is bound by the lifetime of the call. Media monitoring on a call ends as soon the call disconnects or goes idle.

TAPI can obtain device identifiers for various Win32 device classes associated with an opened line by invoking TSPI_lineGetID. This function takes a line handle, address, or call handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open line device, address, or call. If the device class is tapi/line, the device identifier of the line device is returned. If the device class is mci wave, the device identifier of an mci waveaudio device (if supported) is returned that allows the manipulation such as recording or playback of audio over the call on the line.

TAPI can use the returned device identifier with the corresponding media API to query the device's capabilities and subsequently open the media device. For example, if the TAPI client application needs to use the line as a waveform device, it first needs to call waveInGetDevCaps and/or waveOutGetDevCaps to determine the waveform capabilities of the device. The typical waveform data format supported by telephony in North America is 8-bit m-law at 8,000 samples per second, although the wave device driver can convert this sample rate and companding to other more common multimedia audio formats.

To subsequently open a line or address for audio playback using the waveform API, an application calls the waveOutOpen function. The implementation of the waveOutOpen call is device-specific, and each implementation has a number of options for implementing this function. If the call is not answered at the time the function is invoked, for example, the waveOutOpen driver may return an error code message to the application allowing it to display a dialog box stating that "the phone is ringing." This is similar to requesting a CD to play back audio when no compact disc is in the player, and the existing definition of the waveform APIs should handle the situation.


Digit Monitoring

Digit monitoring monitors the call for digits. TSPI enables signaling of digits in two modes:

  • Pulse Digits are signaled as pulse/rotary sequences. For detection, these pulses manifest themselves as nothing more than sequences of audible clicks. Valid pulse digits are '0' through '9'.
  • DTMF Digits are signaled as DTMF (Dual Tone Multi-Frequency) tones. Valid DTMF digits are '0' through '9', 'A'. 'B', 'C', 'D', '*', and '#'. Both the beginning and the down edge of DTMF digits can be monitored.

Digit monitoring can be enabled or disabled on a specified call with TSPI_lineMonitorDigits. If enabled, all detected digits cause TAPI to be notified in the LINE_MONITORDIGITS callback message. The callback provides the call handle on which the digit was detected as well as the digit value and the digit mode. The scope of digit monitoring is bound by the lifetime of the call. Digit monitoring on a call ends as soon the call disconnects or goes idle.


Tone Monitoring

Tone monitoring monitors the media stream of a call for specified tones. A tone is described by its component frequencies and cadence. An implementation of TSPI may allow several different tones to be monitored simultaneously. TSPI uses a two-level identification scheme to identify the tones monitored. There is a tone group and an application-defined tag field, identifying a specific tone within a group.

TAPI can request monitoring for multiple concurrent tone groups, which the service provider should support if it has sufficient resources. Groups are monitored or canceled as a group; there is no finer granularity. Tone monitoring is enabled/disabled on a per-call basis using TSPI_lineMonitorTones.

When tones are detected, the LINE_MONITORTONE callback message notifies TAPI. This message includes the tone-group identifier and the application-specific identifier within that tone group to identify the tone that was detected. An application can tag each tone in order to be able to differentiate tones for which it requests detection. The scope of tone monitoring is bound by the lifetime of the call. Tone monitoring on a call ends as soon the call disconnects or goes idle.

The monitoring of tones, digits, or media types often requires resources that the service provider may have only in finite amounts. A request for monitoring may be rejected if resources are not available. For the same reason, client applications should disable any monitoring that is not needed.


Media Control

TAPI can request the execution of a limited set of media control operations on the call's media stream triggered by telephony events. Although the TAPI clients normally use the media function specifically defined for the media type, media control can yield a significant performance improvement for client/server implementations because simple "detect/control" sequences can be offloaded to the server. The operation TSPI_lineSetMediaControl allows TAPI to specify a list of tuples specifying a telephony event and the associated media-control action, and thus sets up a call's media stream for media control. The telephony events that can trigger media control activities are:

  • Detection of a digit: TAPI provides a list of specific digits and the media control action each of them triggers.
  • Detection of a media type: TAPI provides a list of media types and the media control actions a transition into the media type triggers.
  • Detection of a specified tone: TAPI specifies a list of tones and the media control action each tone detection triggers.
  • Detection of a call state: TAPI specifies a list of call states and the media control action each transition to the call state triggers.

Media control actions are defined generically for the different media types. Not all media streams can provide meaningful interpretations of the media control actions. Operations that may be possible are indicated in LINEMEDIACONTROL_ Constants.

The scope of media control is bounded by the lifetime of the call. Media control on a call ends as soon the call disconnects or goes idle. Only a single media control request can be outstanding on a call across all applications.


Digit Gathering

Besides enabling digit monitoring and being notified of digits one at a time, TAPI can also request that multiple digits be collected in a buffer. Only when the buffer is full or when some other termination condition is met is TAPI notified. Digit gathering is useful for functions such as credit card number collection. TAPI invokes TSPI_lineGatherDigits, specifying a buffer to fill with digits. Digit gathering terminates when one of a number of conditions is true.

  • The requested number of digits has been collected.
  • One of multiple termination digits is detected. The termination digits are specified to TSPI_lineGatherDigits, and the termination digit is placed in the buffer as well.
  • One of two timeouts expires. The timeouts are a first digit timeout, specifying the maximum duration before the first digit must be collected, and an interdigit timeout, specifying the maximum duration between successive digits.
  • Digit gathering is canceled explicitly by invoking TSPI_lineGatherDigits again with either another set of parameters (as with a new buffer) to start a new gathering request or by using a NULL digit buffer parameter to simply cancel.

When terminated for whatever reason, a LINE_GATHERDIGITS message is sent to the application that requested the digit gathering.

Note Only a single digit gathering request can be outstanding on a call at any given time.

Digit gathering and digit monitoring can be enabled on the same call at the same time. In that case, TAPI receives a LINE_MONITORDIGITS message for each detected digit and a separate LINE_GATHERDIGITS message when the buffer is sent back.


Generating Inband Digits and Tones

Information can be transmitted over a call that is in the connected state. Two functions are provided that allow end-to-end inband signaling between TAPI and remote station equipment such as an answering machine. One function is TSPI_lineGenerateDigits, which signals digits over the voice channel on a call. Digits can be signaled as either rotary/pulse sequences or as DTMF tones. The other function is TSPI_lineGenerateTone, which enables TAPI to generate one of a variety of multifrequency tones over the media stream on a call. This generates telephony tones, such as ringback, beep, busy, as well as arbitrary multifrequency multicadenced tones.

Only one digit or tone generation can be in progress on a call at one time. When digit or tone generation completes, a LINE_GENERATE message is sent to TAPI. In the case of generation of multiple digits, only a single message is sent back after all digits are generated. Calling TSPI_lineGenerateDigits or TSPI_lineGenerateTone while digit or tone generation is in progress aborts the generation currently in progress and sends the LINE_GENERATE message to TAPI with a cancel indication.


Media Service Provider Communication

Starting with the Windows 2000 release, telephony service providers that negotiate a version of 3.0 are expected to have a matching media service provider. The precise division of operational responsibilities is implementation dependent. For example, a TSP might use the capabilities of the matching MSP to perform media type determination on an incoming session. However, the TSP must conform to the TSPI, which means getting that determination from the MSP and reporting it to TAPI.

TSPI provides the following functions and messages to allow a virtual connection between a TSP and an MSP.

TSPI_lineCloseMSPInstance
TSPI_lineCreateMSPInstance
TSPI_lineMSPIdentify
TSPI_lineReceiveMSPData

LINE_QOSINFO
LINE_SENDMSPDATA


Phone Devices

Telephony defines a device that supports the phone device class as one that includes some or all of the following elements:

  • Hookswitch/transducer: This is a means for audio input and output. A phone device can have several transducers, which can be activated and deactivated (taken offhook or placed onhook) under application or manual user control. Telephony identifies three types of hookswitch devices common to many phone sets:

    Handset The traditional mouth-and-ear piece combination that must be manually lifted from a cradle and held against the user's ear.

    Speakerphone Enables the user to conduct calls hands-free. The speakerphone may be internal or external to the phone device. The speaker part of a speakerphone allows multiple listeners.

    Headset Enables the user to conduct calls hands-free.

    A hookswitch must be offhook to allow audio data to be sent to and/or received by the corresponding transducer.

  • Volume control/gain control/mute: Each hookswitch device is the pairing of a speaker and a microphone component. Telephony provides for volume control and muting of speaker components and for gain control or muting of microphone components.
  • Ringer: A means for alerting users, usually through a bell. A phone device may be able to ring in a variety of modes or patterns.
  • Display: A mechanism for visually presenting messages to the user. A phone display is characterized by its number of rows and columns.
  • Buttons: An array of buttons. Whenever the user presses a button on the phone set, a report is generated indicating that button press. Button-Lamp identifiers identify a button and lamp pair. Of course, it is possible to have button-lamp pairs with either no button or no lamp. Button-lamp identifiers are integer values that range from 0 to the maximum number of button-lamps available on the phone device, minus one. Each button belongs to a button class. Classes include call appearance buttons, feature buttons, keypad buttons, and local buttons.
  • Lamps: An array of lamps (such as LEDs) that are individually controllable. Lamps can be lit in different modes by varying the on and off frequency. The button-lamp identifier identifies the lamp.
  • Data areas: Memory areas in the phone device where instruction code or data can be downloaded to and/or uploaded from. The downloaded information can affect the behavior (or in other words, program) the phone device.

Telephony allows an application to monitor and control elements of the phone device. The most useful elements for an application are the hookswitch devices. The phone set can act as an audio I/O device (to the computer) with volume control, gain control, and mute; a ringer (for alerting the user); data areas (for programming the phone); and perhaps a display, though the computer's display is more capable. TheTSPI application should not directly control or use phone lamps or phone buttons. Because lamp and button capabilities vary widely among phone sets, the application could be tailored, unwittingly, to specific phone sets.

There is no guaranteed core set of services supported by all phone devices as there is for line devices (the Basic Telephony services). Therefore, before a phone device can be used, its exact capabilities must first be determined. Telephony capability varies with the configuration (client versus client/server), the telephone hardware, and the service-provider software. Applications should make no assumptions as to what telephony capabilities are available.

The capabilities of a phone device are determined by a call to the TSPI_phoneGetDevCaps function. This function queries a specified phone device to determine its telephony capabilities. With a call to this function, the service provider should fill in all the members of the PHONEBUTTONINFO data structure except dwTotalSize, which TAPI fills in. The service provider must not overwrite the dwTotalSize member.

A phone's device capabilities indicate which of these elements exist for each phone device present in the system and what their capabilities are. Although strongly oriented towards real-life telephone sets, this abstraction can provide a meaningful implementation (or subset thereof) for other devices as well. Take as an example a separate headset directly connected and controllable from the computer and operated as a phone device. Hookswitch changes can be triggered by detection of voice energy (offhook) or a period of silence (onhook); ringing can be emulated by the generation of an audible signal into the headset; a display can be emulated through text-to-speech conversion.

A phone device need not be realized in hardware, but can instead be emulated in software using a mouse- or keyboard-driven graphical user interface and the computer's speaker or sound system. Such a soft phone can be an application that uses TAPI. It can also be a service provider, which can be listed as a phone device available to other applications through TAPI, and as such is assigned a phone device identifier.

Phone device support is supplementary rather than basic, so service providers are not required to support phone devices.


Basic Phone Services

Basic phone services are the core set of services supported by all phone devices. Because basic phone services are service-provider defined, there is much variety in the core set.


Phone SPI Initialization

As part of the phone device abstraction defined by TSPI, TAPI and the service provider must first undergo basic initialization. This basic initialization is accomplished both for the line and phone halves of the interface by the same set of steps. The first of these steps is interface version negotiation. TAPI performs this by calling the TSPI_lineNegotiateTSPIVersion function. This function is usually used to negotiate on behalf of an individual line device; different line devices within the same service provider may operate according to different interface versions. TAPI passes a special reserved device identifier value, INITIALIZE_NEGOTIATION, to indicate that it is negotiating an overall interface version for initialization functions that affect the entire service provider, both for lines and phones.

The result of this negotiation is passed to subsequent procedures until a phone device is opened. At that time, the phone device becomes committed to a particular interface version. This interface version is implicit until the phone is closed, and does not need to be passed to subsequent functions that operate on an opened phone.

Following overall interface version negotiation, TAPI calls the TSPI_providerInit function. This function initializes the service provider, also giving it parameters required for subsequent operation. These parameters include the following:

  • dwPermanentProviderID: Specifies the permanent identifier of the service provider being initialized, unique within the service providers on this system.
  • dwLineDeviceIDBase: Specifies the lowest device identifier for the line devices supported by this service provider.
  • dwPhoneDeviceIDBase: Specifies the lowest device identifier for the phone devices supported by this service provider. Devices of the telephony phone device class are identified by integers starting from zero. This range of identifiers is contiguous across the full range of phone devices. Because there may be multiple service providers managing phone devices in a single system, each service provider gets a contiguous portion of the total range. This parameter tells the service provider the lowest value in its portion of the range. The service provider, rather than TAPI, is responsible for mapping this variable range to its own internal device identifiers. This gives the service-provider vendor sufficient flexibility to use device identifiers in device-specific extensions if it wants. Because the service provider knows what device identifiers appear in TAPI-defined parameters and data structures, it can use consistent device identifiers in device-specific extension parameters and data structures.
  • dwNumLines: Specifies how many line devices this service provider supports.
  • dwNumPhones: Specifies how many phone devices this service provider supports.
  • lpfnCompletionProc: Specifies the procedure the service provider calls to report completion of all asynchronously operating procedures on line and phone devices.

Following TSPI_providerInit, normal operations such as opening phones can be carried out.


Opening and Closing Phone Devices

After performing basic initialization and possibly retrieval of device capabilities, TAPI must open the phone device before it can access functions on that phone. After a phone device is successfully opened, TAPI is returned a handle representing the open phone. The function TSPI_phoneOpen opens the specified phone device prior to providing access to functions on the phone. TSPI_phoneClose closes a specified phone device.

A phone device is identified to TSPI_lineOpen by means of its device identifier. This function returns a handle to an open phone. A handle to an open phone device is used in other operations to identify the open phone device. The only functions on phone devices that take a phone device identifier parameter are the early initialization functions such as TSPI_phoneGetDevCaps, TSPI_phoneNegotiateTSPIVersion, TSPI_phoneNegotiateExtVersion, and TSPI_phoneOpen. All other functions take phone handles.

Given a phone handle, the phone's device identifier can be retrieved with the TSPI_phoneGetID function.

The TAPI client application can obtain device identifiers for various Win32 device classes associated with an opened phone by invoking TSPI_phoneGetID with the TAPI phoneGetID function. This function takes a phone handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open phone device. If the device class is tapi/phone, the device identifier of the phone device is returned. If the device class is mci/wave, the device identifier of an mci wave audio device (if supported) is returned that allows the manipulation (such as recording or playback) of audio over the phone.

To subsequently open a phone device for audio playback using the waveform API, an application calls the waveOutOpen function. The implementation of the waveOutOpen call is device specific, and each implementation has a number of options for implementing this function. If the phone's handset is on hook when invoking the function, for example, the waveOutOpen driver may return an error code message to the application that is further mapped in a request (dialog box) to the user to "pick up the phone." This is similar to requesting a CD to play back audio when no compact disc is in the player, and the existing definition of the waveform APIs can deal with it.

In contrast with line devices, for which the basic line services provide the equivalent of POTS, no minimum guaranteed set of functions is defined for phone devices. While each phone device provides at least the functions and messages listed in this section, these operations only provide a way for the software to refer to the phone; they do not offer any true operations on the physical phone device.


Supplementary Phone Services

Supplementary phone services are a set of advanced services beyond basic phone services, supported by phone devices. Typically, this set includes the following device features: hookswitch, display, distinctive ring, buttons, distinctive lamps, data area, and the ability to check call status.


Hookswitch Devices

A phone device can have multiple hookswitch devices. Each hookswitch device has a speaker and a microphone component, and operates in one of four hookswitch modes:

Mode | Meaning
Onhook | The hookswitch device is onhook, and both its microphone and speaker are disabled.
Microphone only | The hookswitch device is offhook, its microphone is enabled, and its speaker is mute.
Speaker only | The hookswitch device is offhook, its microphone is disabled, and its speaker is enabled.
Microphone and speaker | The hookswitch device is offhook, and both the microphone and the speaker are enabled.

TAPI can set and query the hookswitch mode of an opened phone's hookswitch devices. To mute or unmute the microphone or speaker component of a hookswitch device, the TSPI_phoneSetHookSwitch function is used with the appropriate hookswitch mode. This function sets the hookswitch mode of one or more of the hookswitch devices of an open phone device. The TSPI_phoneGetHookSwitch function queries the hookswitch mode of a hookswitch device of an open phone device.

When the mode of a phone's hookswitch device is changed manually, for example by lifting the handset from its cradle, the service provider must send a PHONE_STATE message to the TAPI callback function to notify it about the state change. Parameters to this message provide an indication of the change.

The volume of the speaker component of a hookswitch device can be set with TSPI_phoneSetVolume. The volume setting is different from mute in that muting a speaker and later unmuting it preserves the volume setting of the speaker. The TSPI_phoneGetVolume function returns the volume setting of the hookswitch device's speaker of an open phone device.

The microphone component of a hookswitch device can be gain controlled. The gain setting is different from mute in that muting a microphone and later unmuting it preserves the gain setting of the microphone. TSPI_phoneSetGain sets the gain of a hookswitch device's microphone of an open phone device, and TSPI_phoneGetGain returns the gain setting of the hookswitch device's microphone of an opened phone.

When the volume or gain of a phone's hookswitch device is changed, the service provider sends a PHONE_STATE message to the TAPI callback function to notify TAPI about the state change. Parameters to this message provide an indication of the change.


Display

TSPI provides access to a phone's display. The display is modeled as an alphanumeric area with rows and columns. A phone's device capabilities indicate the size of a phone's display as number of rows and number of columns. Both these numbers are zero if the phone device does not have a display. The TSPI_phoneSetDisplay function writes information to the display of an open phone device. TSPI_phoneGetDisplay returns the current contents of a phone's display.

When the display of a phone device is changed, the service provider sends a PHONE_STATE message to the TAPI callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Ring

A single phone may be able to ring with different ring modes. Given the wide variety of ring modes available, ring modes are identified by their ring mode number. A ring mode number ranges from zero to the number of available ring modes, with ring mode 0 indicating silence.

TSPI_phoneSetRing rings an open phone device according to a given ring mode. TSPI_phoneGetRing returns the current ring mode of an opened phone device.

When the ring mode of a phone device is changed, the service provider sends a PHONE_STATE message to the TAPI callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Buttons

Microsoft Telephony models a phone's buttons and lamps as button-lamp pairs. A button with no lamp next to it, or a lamp with no button is specified using a dummy indicator for the missing lamp or button. A button with multiple lamps is modeled by using multiple button-lamp pairs.

Information associated with a phone button can be set and retrieved. When a button is pressed, the service provider sends a PHONE_BUTTON message to the TAPI callback function. Parameters of this message are a handle to the phone device and the button/lamp identifier of the button that was pressed. The keypad button '0' through '9', '*', and '#' are assigned fixed button/lamp identifiers 0 through 11.

The function TSPI_phoneSetButtonInfo sets the information associated with a button on a phone device. TSPI_phoneGetButtonInfo returns information associated with a button on a phone device. The service provider sends a PHONE_BUTTON message to the TAPI callback function when a button on the phone is pressed.

The information associated with a button does not carry any semantic meaning as far as TSPI is concerned. It is useful for device-specific applications that interpret this information for a given phone device, or for display to the user, such as in an application's help system.


Lamps

The lamps on a phone device can be lit in a variety of different lighting modes. Unlike ringing patterns, lamp modes are more uniform across phone sets of different vendors. A common set of lamp modes is defined by Microsoft Telephony. A lamp identified by its lamp/button identifier can be lit in a given lamp mode. A lamp can also be queried for its current lamp mode.

The lamp functions are TSPI_phoneSetLamp, which lights a lamp on a specified open phone device in a given lamp lighting mode, and TSPI_phoneGetLamp, which returns the current lamp mode of the specified lamp.

When a lamp mode of a phone device is changed, the service provider sends a PHONE_STATE message to the TAPI callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Data Areas

Some phone sets support the capability of downloading data from or uploading data to the phone device, which allows the phone set to be programmed in a variety of ways. Microsoft Telephony models these phone sets as having one or more download or upload areas. Each area is identified by a number that ranges from zero to the number of data areas available on the phone minus one. Sizes of each area can vary. The format of the data itself is device specific.

The TSPI_phoneSetData function downloads a buffer of data to a given data area in the phone device. TSPI_phoneGetData uploads the contents of a given data area in the phone device to a buffer.

When a data area of a phone device is changed, the service provider sends a PHONE_STATE message to the TAPI callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Status

Most of the Get and Set operations described in the topics in this section deal with only one component of information. The operation TSPI_phoneGetStatus allows TAPI to obtain complete status information about a phone device.

Whenever a status item changes on the phone device, the service provider sends a PHONE_STATE message to the TAPI callback function. The message parameters include a handle to the phone device and an indication of the status item that changed. TAPI can use TSPI_phoneSetStatusMessages to select status changes for which it wants to be notified in the callback message. In contrast TAPI, there is no corresponding TSPI_phoneGetStatusMessages function. The TAPI tracks which applications have enabled which status messages.


Extended Phone Services

The Extended Phone Services (or device-specific phone services) include all extensions to TSPI defined by the service-provider. TSPI defines a mechanism that enables service-provider vendors to extend TSPI using device-specific extensions. TSPI only defines the extension mechanism, and by doing so provides access to device-specific extensions, whose behavior is completely defined by the service provider.

TSPI consists of scalar and bit-flag data constant definitions, data structures, functions, and callback messages. Procedures are defined that enable a vendor to extend most of these, as described in the topics in this section.


Scalar Data Constants

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. As most data constants are DWORDs, typically the range 0x00000000 through 0x7FFFFFFF is reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF are available for vendor-specific extensions. The assumption is that a vendor can define values that are natural extensions of the datatypes defined by TSPI.


Bit-Flag Data Constants

For extensible bit flag data constants, a service-provider vendor can define new values for specified bits. As most bit flag constants are DWORDs, typically a specific number of the lower bits are reserved for common extensions while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up, and vendor-specific extensions should be assigned from bit 31 down. This provides maximum flexibility in assigning bit positions to common extensions versus vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by TSPI.

Extensible data structures have a variably sized field that is reserved for device-specific use. Being variably sized, the service provider decides the amount of information and the interpretation. A vendor that defines a device-specific member is expected to make these natural extensions of the original data structure defined by TSPI.


Functions and Messages

The TSPI_phoneDevSpecific function and associated PHONE_DEVSPECIFIC message enable the TAPI client application to access device-specific phone features that are unavailable through the common telephony services on phones. The parameter profile of the TSPI_phoneDevSpecific function is generic in that little interpretation of the parameters is made by TSPI. Device-handle parameters have TSPI-defined meanings and are translated appropriately between the application and the service provider. Generic parameters are simply passed through unmodified. The interpretation of the generic parameters is defined by the service provider and must be understood by any applications that use them. An application that relies on device-specific extensions will not generally work with other service providers. However, applications written entirely to the common telephony phone services will work with the extended service provider.

Regarding handle translation, the passthrough nature of the generic parts of device-specific extensions has an imporant consequence. A service provider has no way to relate the handles used at the TSPI level to those at the TAPI level except by passing them through the predefined handle parameters and fields. Any handle put into the generic extension area is untranslated by TAPI as it is passed between application and service provider. The designer of a service-provider extension should generally not define extensions that pass handles in this way.

The appropriate approach to define a device-specific extension that needs to refer to specific devices without using handles is to refer to them using their absolute device identification. The device identifier used in opening a phone at the TAPI level, for example, is strictly the same value that is used at the TSPI level to open the phone.

This is the motivation for the dwPhoneDeviceIDBase parameter in the TSPI_providerInit function. It adjusts the service provider's device identifier numbering to be the same as the numbering used at the TAPI level. This gives the service-provider designer the flexibility to use device identifiers to identify devices in device-specific extensions.

There is no central registry for manufacturer identifiers. Instead a unique identifier generator, called Extidgen.exe, is made available as part of TSPI. The vendor that designs a set of device-specific extensions uses this utility to obtain a unique identifier for those extensions. This unique identifier must be published as part of the specification of the extensions to allow application developers to access the extensions.


Asynchronous Phone Operations

There are nine asynchronous operations related to phones. These are initiated by the TSPI_phoneDevSpecific, TSPI_phoneSetButtonInfo, TSPI_phoneSetData, TSPI_phoneSetDisplay, TSPI_phoneSetGain, TSPI_phoneSetHookSwitch, TSPI_phoneSetLamp, TSPI_phoneSetRing, and TSPI_phoneSetVolume functions. If an application calls the TAPI phoneClose function and has the only handle to the phone, TAPI calls the TSPI_phoneClose function to direct the service provider to terminate the asynchronous operations and call the ASYNC_COMPLETION callback function as appropriate. If the application does not have the only handle to the phone, the service provider receives no notification of the request and any outstanding asynchronous operations remain active.


The Telephony Service Provider UI DLL Interface

In Microsoft Telephony, telephony service providers execute in a separate process from telephony applications. Service providers communicate with Tapisrv.exe through the Telephony service provider interface (TSPI) and execute in its process; applications interface to TAPI, which are loaded in the application context.

The components of TAPI use various interprocess communications mechanisms to convey function requests and messages between applications and service providers. The applications and the service providers may be executing not only in separate processes, but on completely separate systems. Service providers therefore cannot display dialog boxes in the process or even on the computer on which they are executing; UI must be invoked from within the application context, on the computer on which the application is executing.

This section defines the mechanism by which service provider UI functions are loaded and invoked within the application context. A mechanism is also defined by which service providers can spontaneously open dialog boxes in the application context when they would not otherwise be expected by the application. An example of this latter case would be the Talk/Hangup dialog box that is displayed by a data modem service provider when the modem is being used as a dialer for interactive voice calls, and the user must be told to pick up the phone and inform the service provider when to place the modem onhook.


Architecture

The following illustration shows the general architecture of telephony service providers and their associated user interface dynamic-link libraries (UI DLLs).

The service provider consists of a minimum of two components. The service provider DLL (designated in the illustration as MAIN.TSP) executes in the context of the Tapisrv.exe process, and performs all of the tasks of the service provider that are not related to user interface elements associated with a particular application's use of the device (most likely, in conjunction with lower-level components not shown in the illustration). But unlike previous versions of TAPI in which the user interface code was integrated into the service provider (and executed, because of the previous architecture, within the context of the application), the service provider must now include a separate component that implements the user interface elements.

The service provider UI DLL must be a Win32 (32-bit) DLL. It must export functions that are called by TAPI when the application calls TAPI functions that generate UI: TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, and TUISPI_providerRemove. Each of these functions includes as a parameter a pointer to a callback function in TAPI, of type TUISPIDLLCALLBACK, which the UI DLL can use to communicate bidirectionally (both send and receive data) with the service provider DLL executing in the TAPISRV process. If the service provider ever generates spontaneous UI, such as the Unimodem Talk/Hangup dialog box, in conjunction with any TSPI function for which UI is not expected (for example, any function that does not have an hwnd parameter), then the UI DLL must export TUISPI_providerGenericDialog and TUISPI_providerGenericDialogData.

Note The original TSPI UI-generating functions (TSPI_lineConfigDialog, TSPI_lineConfigDialogEdit, TSPI_phoneConfigDialog, TSPI_providerConfig, TSPI_providerInstall, and TSPI_providerRemove) are obsolete and never called by TAPI. Therefore, these are not required to be exported by the service provider DLL. However, if the service provider wants to be listed as one that can be added by the Telephony Control Panel, a utility supplied with Windows Telephony in versions 1.4 and earlier, it must export TSPI_providerInstall; if it wants to have the Remove button enabled in the Telephony Control Panel when it is selected, it must export TSPI_providerRemove; and if it wants the Setup button to be enabled in the Telephony Control Panel when it is selected, it must export TSPI_providerConfig. The Telephony Control Panel checks for the presence of these functions in the service provider TSP file to adjust its user interface to reflect which operations can be performed.

The service provider DLL must export the TSPI_providerUIIdentify function that Tapisrv.exe process uses to obtain the name of the UI DLL to load in the application process. It must export the TSPI_providerGenericDialogData function to receive and respond to requests from the UI DLL for data to display, and it must export TSPI_providerFreeDialogInstance for Tapisrv.exe process to tell the service provider when to release an association established for the purpose of generating spontaneous UI in conjunction with a function that is not defined as presenting UI to the user. The service provider DLL can unidirectionally send data to the UI DLL by using the new TSPI message LINE_SENDDIALOGINSTANCEDATA.

Because the names of the TSPI and TUISPI functions are intentionally defined to be different, the service provider DLL and the UI DLL can be the same DLL file, if desired. With proper segmentation, this does not necessarily result in any unnecessary usage of memory in the application context, and can simplify the installation process for service providers that can currently be implemented in a single DLL. TAPI calls only the functions that are appropriate for the context in which the DLL is being used.

The telephony service provider and the UI DLL must both be designed with the requirement in mind that the UI functions can be invoked from multiple application processes simultaneously. They must also consider that the application and the TAPI service under which the telephony service provider is executing can be on separate computers on a LAN.


Usage

There are two general cases of usage of the TSP UI DLL interface: when the application invokes a function that is designed to generate UI, and when the service provider must spontaneously generate UI in the course of processing a function that is not defined as generating UI.


Functions Designed to Generate UI

Assume for the purposes of an example that the application calls the TAPI lineConfigDialog function, which is designed to open a dialog box to allow configuration of service provider options related to the specified line device. In response to this call, TAPI requests TAPISRV to call TSPI_providerUIIdentify in the telephony service provider, obtaining the name of the TSP UI DLL.

In the application's context, TAPI loads the TSP UI DLL and calls the TUISPI_lineConfigDialog function with the parameters supplied by the application, and including a pointer to the TAPI TUISPIDLLCALLBACK function. The TSP UI DLL displays the configuration dialog box, calling the TUISPIDLLCALLBACK function as necessary to obtain from the telephony service provider the information to display. Each time the TUISPIDLLCALLBACK function is called, TAPI requests TAPISRV to call the telephony service provider's TSPI_providerGenericDialogData function, passing in the parameter block from the UI DLL, and returning the parameter block to the UI DLL. The UI DLL conveys any configuration changes to the telephony service provider by calling TUISPIDLLCALLBACK.

When the function is complete, the UI DLL returns from (in this case) TUISPI_lineConfigDialog. TAPI calls the Win32 FreeLibrary function to release the UI DLL, and returns to the application.


Functions Not Designed to Generate UI

Assume that the service provider must display a dialog box (like the Unimodem or ATSP Talk/Hangup dialog box) during the processing of lineMakeCall or lineDial. In this case, it is the service provider, not the application, that decides that UI must be displayed.

To invoke the UI DLL in the application process, the service provider calls the TSPI LINEEVENT callback, generating a LINE_CREATEDIALOGINSTANCE message, passing in a pointer to a structure of type TUISPICREATEDIALOGINSTANCEPARAMS. This structure contains the dwRequestID of the function with which the UI is associated, allowing TAPISRV to identify the client application in which the UI is to be generated.

TAPISRV requests the correct application's instance of TAPI to load the UI DLL and create a thread for the UI within the application's process. From this new UI thread, TAPI calls the UI DLL's TUISPI_providerGenericDialog function, passing in data that was specified by the telephony service provider in the structure passed in with the LINE_CREATEDIALOGINSTANCE message; the UI DLL displays the appropriate dialog box (which is a matter for private design between the UI DLL and the telephony service provider). The UI DLL does not return from TUISPI_providerGenericDialog until the dialog box is closed.

The telephony service provider can generate updated data to display in the dialog box (or, for example, instruct the dialog box to be closed, if the call is abandoned or other events occur) by sending a LINE_SENDDIALOGINSTANCEDATA message. TAPISRV conveys the data to TAPI, which calls the UI DLL's TUISPI_providerGenericDialogData function. This mechanism provides a unidirectional "send" to the UI DLL. If the UI DLL wants to inform the telephony service provider of the results of the dialog box or obtain other data, it can call the TUISPIDLLCALLBACK function (a pointer to which it received when TUISPI_providerGenericDialog was called).

When the dialog box is dismissed, TUISPI_providerGenericDialog returns to TAPI. TAPI calls FreeLibrary to release the UI DLL, and exits the UI thread it had created in the application context. It then requests TAPISRV to call the telephony service provider's TSPI_providerFreeDialogInstance function to unbind the association created when the telephony service provider originally sent the LINE_CREATEDIALOGINSTANCE message. This function is also called if the application process terminates unexpectedly before TUISPI_providerGenericDialog returns.


TSPI Reference

The following material is the primary reference for the Telephony Service Provider Interface (TSPI).


TSPI Functions

This section contains an alphabetic list of the service provider, line device, phone device, and callback functions in the Telephony Service Provider Interface (TSPI) and the Telephony User Interface Service Provider Interface (TUISPI).


TSPI Quick Function Reference

The following hyperlinked summary of TSPI functions is organized by category of operation.

TSPI Service Provider Functions

TSPI Line Device Functions

TSPI Phone Device Functions

TSPI Callback Functions

TSP UI DLL Functions

TUISPI Service Provider Functions

TUISPI Line Device Functions

TUISPI Phone Device Functions

TUISPI Callback Functions


TSPI Basic Telephony Functions

All service providers must implement Basic Telephony functions. The following is a list of such functions by category. A function is identified as asynchronous if it indicates completion in a REPLY message to the application. If the function always returns its result immediately, the function is considered synchronous.

Addresses

Answering Incoming Calls

Call Drop Functions

Call States and Events

Line Status and Capabilities

Line Version Negotiation

Making Calls

Opening and Closing Line Devices

TSP Initialization and Shutdown

TSP Initialization and Shutdown

TUISPI_providerInstall | Installs a TSP. Synchronous.
TSPI_providerInstall | Installs the TSP. Obsolete with Version 2.0. Synchronous.
TSPI_providerInit | Initializes the TSP. Synchronous.
TUISPI_providerRemove | Removes a TSP. Synchronous.
TSPI_providerRemove | Removes a TSP. Obsolete with Version 2.0. Synchronous.

Line Version Negotiation

TSPI_lineNegotiateTSPIVersion Allows an application to negotiate a TSPI version to use with a given line device. Synchronous.

Line Status and Capabilities

TSPI_lineGetDevCaps | Returns the capabilities of a given line device. Synchronous.
TSPI_lineGetDevConfig | Returns configuration of a media stream device. Synchronous.
TSPI_lineGetLineDevStatus | Returns current status of the specified open line device. Synchronous.
TSPI_lineSetDevConfig | Sets the configuration of the specified media stream device. Synchronous.
TSPI_lineSetStatusMessages | Specifies the status changes for which the application needs to be notified. Synchronous.
TSPI_lineGetID | Retrieves a device ID associated with the specified open line, address, or call. Synchronous.
TSPI_lineGetIcon | Allows an application to retrieve an icon for display to the user. Synchronous.
TUISPI_lineConfigDialog | Causes the provider of the specified line device to display a dialog box that allows the user to configure parameters related to the line device. Synchronous.
TUISPI_lineConfigDialogEdit | Displays a dialog box allowing the user to change configuration information for a line device. Synchronous.

Addresses

TSPI_lineGetAddressCaps | Returns the telephony capabilities of an address. Synchronous.
TSPI_lineGetAddressStatus | Returns current status of a specified address. Synchronous.
TSPI_lineGetAddressID | Retrieves the address ID of an address specified using an alternate format. Synchronous.

Opening and Closing Line Devices

TSPI_lineOpen | Opens a specified line device for providing subsequent monitoring and/or control of the line. Synchronous.
TSPI_lineClose | Closes a specified opened line device. Synchronous.

Call States and Events

TSPI_lineGetCallInfo | Returns fixed information about a call. Synchronous.
TSPI_lineGetCallStatus | Returns complete call status information for the specified call. Synchronous.
TSPI_lineSetAppSpecific | Sets the application-specific field of a call's information structure. Synchronous.

Making Calls

TSPI_lineMakeCall | Makes an outbound call and returns a call handle for it. Asynchronous.
TSPI_lineDial | Dials (parts of one or more) dialable addresses. Asynchronous.

Answering Incoming Calls

TSPI_lineAnswer Answers an incoming call. Asynchronous.

Call Drop Functions

TSPI_lineDrop Disconnects a call, or abandons a call attempt in progress. Asynchronous.


TSPI Service Provider Functions

This section documents TSPI service provider functions. These functions include:

  • TSPI_providerConfig
  • TSPI_providerCreateLineDevice
  • TSPI_providerCreatePhoneDevice
  • TSPI_providerEnumDevices
  • TSPI_providerInit
  • TSPI_providerInstall
  • TSPI_providerRemove
  • TSPI_providerShutdown


TSPI_providerConfig

The TSPI_providerConfig function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_providerConfig.

The TSPI_providerConfig function gathers configuration information from the user. It may use a dialog box, and this dialog box can include sub-dialog boxes associated with other APIs (such as Comm/datamodem) for the setup of specific devices.

LONG TSPIAPI TSPI_providerConfig(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the configuration.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_NOMEM.

Remarks

This function may be called while the service provider is in use (that is, between calls of TSPI_providerInit and TSPI_providerShutdown).

Any changes that affect the behavior visible through TSPI should take effect only when the service provider is restarted at the next TSPI_providerInit.

The Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier calls this function when the setup command is invoked.

There is no directly corresponding function at the TAPI level. In TAPI, applications have access to the functions lineConfigDialog and phoneConfigDialog, which allow configuration of parameters of a particular line or phone once it has been installed.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tspi.h.

See Also

TSPI_lineConfigDialog, TSPI_phoneConfigDialog, TSPI_providerInstall, TSPI_providerRemove, TUISPI_providerConfig


TSPI_providerCreateLineDevice

The TSPI_providerCreateLineDevice function is called by TAPI in response to receipt of a LINE_CREATE message from the service provider, which allows the dynamic creation of a new line device.

LONG TSPIAPI TSPI_providerCreateLineDevice(
  DWORD_PTR dwTempID,
  DWORD dwDeviceID
);

Parameters

dwTempID
The temporary device identifier that the service provider passed to TAPI in the LINE_CREATE message.
dwDeviceID
The device identifier that TAPI assigns to this device if this function succeeds.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Remarks

When TAPI receives a LINE_CREATE message from a service provider, it calls this function (it never calls this function spontaneously). TAPI adds 1 to the number of devices of that type, and passes the resulting new, unused device identifier as the dwDeviceID parameter to this function. It also passes in the function the dwParam2 parameter from the LINE_CREATE message as dwTempID.

Note Adding the new device to the end of the device list is likely to produce noncontiguous device identifiers for the service provider; service providers that support dynamic device creation must also support noncontiguous device identifiers.

If the service provider recognizes the dwTempID and succeeds in setting up the structures and such that it needs to support the new device, it saves off the dwDeviceID, and returns SUCCESS. If this function is unsuccessful, TAPI doesn't add the device, and there are no negative effects (the LINE_CREATE message is ignored). If this function completes successfully, TAPI then informs applications of the availability of the new device using LINE_CREATE or LINE_LINEDEVSTATE (LINEDEVSTATE_REINIT) messages.

Older service providers that do not export this function, however, also should not send LINE_CREATE messages, which means TAPI would not try to call this function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CREATE, LINE_LINEDEVSTATE


TSPI_providerCreatePhoneDevice

The TSPI_providerCreatePhoneDevice function is called by TAPI in response to receipt of a PHONE_CREATE message from the service provider, which allows the dynamic creation of a new phone device.

LONG TSPIAPI TSPI_providerCreatePhoneDevice(
  DWORD_PTR dwTempID,
  DWORD dwDeviceID
);

Parameters

dwTempID
The temporary device identifier that the service provider passed to TAPI in the PHONE_CREATE message.
dwDeviceID
The device identifier that TAPI assigns to this device if this function succeeds.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Remarks

When TAPI receives a PHONE_CREATE message from a service provider, it calls this function (it never calls this function spontaneously). TAPI adds 1 to the number of devices of that type, and passes the resulting new, unused device identifier as the dwDeviceID parameter to this function. It also passes in the function the dwParam2 parameter from the PHONE_CREATE message as dwTempID. Adding the new device to the end of the device list is likely to produce noncontiguous device identifiers for the service provider; service providers that support dynamic device creation must also support noncontiguous device identifiers.

If the service provider recognizes the dwTempID parameter and succeeds in setting up the structures and such that it needs to support the new device, it saves off the dwDeviceID, and returns SUCCESS. If this function is unsuccessful, TAPI doesn't add the device, and there are no negative effects (the PHONE_CREATE message is ignored). If this function completes successfully, TAPI informs applications of the availability of the new device using PHONE_CREATE or PHONE_STATE (PHONESTATE_REINIT) messages.

Older service providers that do not export this function, however, also should not send PHONE_CREATE messages, which means TAPI would not try to call this function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

PHONE_CREATE, PHONE_STATE


TSPI_providerEnumDevices

TAPI calls the TSPI_providerEnumDevices function before TSPI_providerInit to determine the number of line and phone devices supported by the service provider.

LONG TSPIAPI TSPI_providerEnumDevices(
  DWORD dwPermanentProviderID,
  LPDWORD lpdwNumLines,
  LPDWORD lpdwNumPhones,
  HPROVIDER hProvider,
  LINEEVENT lpfnLineCreateProc,
  PHONEEVENT lpfnPhoneCreateProc
);

Parameters

dwPermanentProviderID
The permanent identifier, unique within the service providers on this system, of the service provider being initialized.
lpdwNumLines
A pointer to a DWORD-sized memory location into which the service provider must write the number of line devices it is configured to support. TAPI initializes the value to 0, so if the service provider fails to write a different value, the value 0 is assumed.
lpdwNumPhones
A pointer to a DWORD-sized memory location into which the service provider must write the number of phone devices it is configured to support. TAPI initializes the value to 0, so if the service provider fails to write a different value, the value 0 is assumed.
hProvider
An opaque DWORD-sized value that uniquely identifies this instance of this service provider during this execution of the Win32 Telephony environment.
lpfnLineCreateProc
A pointer to the LINEEVENT callback procedure supplied by TAPI. The service provider uses this function to send LINE_CREATE messages when a new line device needs to be created.
lpfnPhoneCreateProc
A pointer to the PHONEEVENT callback procedure supplied by TAPI. The service provider uses this function to send PHONE_CREATE messages when a new phone device needs to be created.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Remarks

In previous versions of TAPI, implementation of this function was optional. Beginning with TAPI 2.0, implementation of this function is mandatory in all service providers. TAPI no longer checks Telephon.ini or the Registry at TAPI startup to determine the initial number of lines and phones supported by a service provider.

A new device can appear prior to the completion of the TSPI_providerInit procedure. TAPI handles properly any _CREATE messages during the provider initialization.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CREATE, LINEEVENT, PHONE_CREATE, PHONEEVENT, TSPI_providerInit


TSPI_providerInit

The TSPI_providerInit function initializes the service provider and gives it parameters required for subsequent operation.

LONG TSPIAPI TSPI_providerInit(
  DWORD dwTSPIVersion,
  DWORD dwPermanentProviderID,
  DWORD dwLineDeviceIDBase,
  DWORD dwPhoneDeviceIDBase,
  DWORD_PTR dwNumLines,
  DWORD_PTR dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD lpdwTSPIOptions
);

Parameters

dwTSPIVersion
The version of the TSPI definition under which this function must operate. The caller can use TSPI_lineNegotiateTSPIVersion with the special dwDeviceID INITIALIZE_NEGOTIATION to negotiate a version that is guaranteed to be acceptible to the service provider.
dwPermanentProviderID
The permanent identifier, unique within the service providers on this system, of the service provider being initialized.
dwLineDeviceIDBase
The lowest device identifier for the line devices supported by this service provider.
dwPhoneDeviceIDBase
The lowest device identifier for the phone devices supported by this service provider.
dwNumLines
The number of line devices this service provider supports. The value returned is the number of line devices reported in TSPI_providerEnumDevices.
dwNumPhones
The number of phone devices this service provider supports. The value returned is the number of phone devices reported in TSPI_providerEnumDevices.
lpfnCompletionProc
The procedure the service provider calls to report completion of all asynchronously operating procedures on line and phone devices.
lpdwTSPIOptions
A pointer to a DWORD-sized memory location, into which the service provider can write a value specifying LINETSPIOPTIONS_ values. This parameter allows the service provider to return bits indicating optional behaviors desired of TAPI. TAPI sets the options DWORD to 0 before calling TSPI_providerInit, so if the service provider doesn't want any of these options, it can just leave the DWORD set to 0.

At this time, only one bit is defined to be returned through this pointer: LINETSPIOPTION_NONREENTRANT. The service provider sets this bit if it is not designed for fully pre-emptive, multithreaded, multitasking, multiprocessor operation (for example, updating of global data protected by mutexes). When this bit is set, TAPI only makes one call at a time to the service provider; it does not call any other entry point, nor that entry point again, until the service provider returns from the original function call. Without this bit set, TAPI may call into multiple service provider entry points, including multiple times to the same entry point, simultaneously (actually simultaneously in a multiprocessor system).

Important Note It must be emphasized that setting this bit degrades performance. It is strongly recommended that this be used only for development but not a shipped production service provider.

TAPI does not serialize access to TSPI functions that display a dialog box (TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove) so that they do not block other TSPI functions from being called; the service provider must include internal protection on these functions.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Remarks

This function is guaranteed to be called before any of the other functions prefixed with TSPI_line or TSPI_phone except TSPI_lineNegotiateTSPIVersion. It is strictly paired with a subsequent call to TSPI_providerShutdown These pairs may overlap, for example, when the Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier is used while telephony operations are in progress. The call to this function must be ignored (returning success) if there is already an outstanding pair.

A service provider should perform as many consistency checks as is practical at the time. TSPI_providerInit is called to ensure that it is ready to run. Some consistency or installation errors, however, cannot be detected until the operation is attempted. The error LINEERR_NODRIVER can be used to report such nonspecific errors at the time they are detected.

There is no directly corresponding function at the TAPI level. At that level, multiple different usage instances can be outstanding, with an "application handle" returned to identify the instance in subsequent operations. At TSPI level, the interface architecture supports only a single usage instance for each distinct service provider.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineNegotiateTSPIVersion, TSPI_providerShutdown, TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove


TSPI_providerInstall

The TSPI_providerInstall function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_providerInstall.

The TSPI_providerInstall function installs any additional "pieces" of the provider into the right directories (or at least verifying that they're there), sets up the provider's registry entries for its lines and phones, and creates any other entries necessary for the service provider. It is called from the Telephony Control Panel utility (supplied with Windows Telephony in versions 1.4 and earlier) when the Add button is pressed.

LONG TSPIAPI TSPI_providerInstall(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
The handle of the parent window in which the function can create any dialog box windows that are required during installation.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM. LINEERR_INVALPARAM.

Remarks

This function completes the installation of other pieces required by the service provider after its entries in the [Providers] section in the registry have been made. If the service provider requires any additional privately-defined entries in the registry for proper operation, they must also be installed. A typical way to install this section with its entries is to call TSPI_providerConfig.

This function must leave the system in a consistent state. It should run to completion, not allowing the user to abort the installation when it is partly completed. If installation fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete installation is possible, before the installation begins.

This function is called only once, during installation of the service provider, until there is a call to TSPI_providerRemove. It must be called before any other TSPI-defined function.

The Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier calls this function (with external sequence requirements met as described here) when the "add" command is invoked. It does not call TSPI_providerConfig for the "add" command.

There is no corresponding function at the TAPI level. At that level, applications expect to have service providers already installed. Running applications are informed about dynamic reconfiguration through the LINEDEVSTATE_REINIT or PHONESTATE_REINIT value in the LINE_LINEDEVSTATE or PHONE_STATE message.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tspi.h.

See Also

LINE_LINEDEVSTATE, PHONE_STATE, TSPI_providerConfig, TSPI_providerInit, TSPI_providerRemove, TSPI_providerShutdown


TSPI_providerRemove

The TSPI_providerRemove function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_providerRemove.

The TSPI_providerRemove function asks the user to confirm elimination of the service provider. It is the responsibility of the service provider to remove any registry entries that the service provider added at addProvider time, as well as any other modules and files that are no longer needed.

LONG TSPIAPI TSPI_providerRemove(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the removal.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarks

This function must guarantee that the service provider's section and privately-defined information for the service provider is removed from the registry if it returns success. In particular, the [Provider<PPID>] section whose <PPID> matches dwPermanentProviderID must be removed, including its NumLines and NumPhones entries. If the function returns success, it is the caller's responsibility to remove the matching ProviderIDx and ProviderFilenamex entries from the [Providers] section, and renumber the remaining entries in the [Providers] section accordingly.

This procedure must leave the system in a consistent state. It should run to completion, not allowing the user to abort the removal when it is partly completed. If removal fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete removal is possible, before the removal begins.

This function can be called while the service provider is in use (that is, between TSPI_providerInit and TSPI_providerShutdown). If this happens, the service provider should do an appropriate combination of displaying a user dialog box to announce any conflict and confirm removal, restricting removal options to those that can be performed transparently, or issuing LINE_CLOSE and PHONE_CLOSE messages to inform TAPI and applications that the affected devices have been forcibly closed for removal. In any case, any changes that affect the behavior visible through TSPI should take effect only when the service provider is shut down at the next TSPI_providerShutdown.

This function should not return LINEERR_INUSE or other errors that might occur because the provider is in use by an application; instead, the provider should confer with the user directly about this problem, and then return LINEERR_OPERATIONFAILED if the user decides to abort the operation.

This procedure is called only once, at the time of removal of the service provider, until there is a call to TSPI_providerInstall. It is the responsibility of the caller to ensure this.

The Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier calls this function (with external sequence requirements met as described here) when the "remove" command is invoked.

There is no corresponding function at the TAPI level. At that level, applications expect to have service providers already installed; otherwise their lines and phones do not appear within the available sequence of device identifiers. Running applications are informed about dynamic reconfiguration, including removal of service providers, through the LINEDEVSTATE_REINIT or PHONESTATE_REINIT value in the LINE_LINEDEVSTATE or PHONE_STATE message.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tspi.h.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, PHONE_CLOSE, PHONE_STATE, TSPI_providerInit, TSPI_providerInstall, TSPI_providerShutdown


TSPI_providerShutdown

The TSPI_providerShutdown function shuts down the service provider. The service provider terminates any activities it has in progress and releases any resources it has allocated.

LONG TSPIAPI TSPI_providerShutdown(
  DWORD dwTSPIVersion,
  DWORD dwPermanentProviderID
);

Parameters

dwTSPIVersion
The version of the TSPI definition under which this function must operate. The caller can use TSPI_lineNegotiateTSPIVersion or TSPI_phoneNegotiateTSPIVersion with the special dwDeviceID INITIALIZE_NEGOTIATION to negotiate a version that is guaranteed to be acceptible to the service provider.
dwPermanentProviderID
This parameter allows the service provider to determine which among multiple possible instances of the service provider is being shut down. The value of the parameter is identical to that passed in the parameter of the same name in TSPI_providerInit.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM.

Remarks

The final paired call to this function must be the last call to any of the TSPI functions prefixed with TSPI_line or TSPI_phone other than TSPI_lineNegotiateTSPIVersion, or TSPI_phoneNegotiateTSPIVersion. It is the caller's responsibility to ensure this.

This function should always succeed except in extraordinary circumstances. Most callers will probably ignore the return code because they will be unable to compensate for any error that occurs. The specified return values are more advisory for development diagnostic purposes than anything else.

There is no directly corresponding function in TAPI. In TAPI, multiple different usage instances can be outstanding, with an "application handle" parameter to identify the instance to be operated on. In TSPI, the interface architecture supports only a single usage instance for each distinct service provider.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineNegotiateTSPIVersion, TSPI_phoneNegotiateTSPIVersion, TSPI_providerInit


TSPI Line Device Functions

This section contains an alphabetic list of the available line device functions in the Telephony SPI. The information for each function includes the following:

  • A statement of the function's purpose.
  • The correct syntax for the function.
  • A description of the function's parameters, including valid call states.
  • A description of the function's return value.
  • A Remarks section that can include any or all of the following: a list of the valid call states on entry of the function and typical call state transitions when the request completes; a description of which members of large data structures must be filled in by the service provider and which members must have their values preserved intact; and comparison with a corresponding function within TAPI.
  • References to other functions, messages, or data structures.

    Note The actual states in which a function can be performed may be limited by the capabilities of the service provider. Service providers must set the dwCallFeatures member in the LINECALLSTATUS structure, the dwAddressFeatures member in the LINEADDRESSSTATUS structure, and the dwLineFeatures member in the LINEDEVSTATUS structure to indicate to applications whether or not a function is permitted at that point in time.

This section contains the following TSPI line device functions:

  • TSPI_lineAccept
  • TSPI_lineAddToConference
  • TSPI_lineAnswer
  • TSPI_lineBlindTransfer
  • TSPI_lineClose
  • TSPI_lineCloseCall
  • TSPI_lineCloseMSPInstance
  • TSPI_lineCompleteCall
  • TSPI_lineCompleteTransfer
  • TSPI_lineConditionalMediaDetection
  • TSPI_lineConfigDialog
  • TSPI_lineConfigDialogEdit
  • TSPI_lineCreateMSPInstance
  • TSPI_lineDevSpecific
  • TSPI_lineDevSpecificFeature
  • TSPI_lineDial
  • TSPI_lineDrop
  • TSPI_lineDropNoOwner
  • TSPI_lineDropOnClose
  • TSPI_lineForward
  • TSPI_lineGatherDigits
  • TSPI_lineGenerateDigits
  • TSPI_lineGenerateTone
  • TSPI_lineGetAddressCaps
  • TSPI_lineGetAddressID
  • TSPI_lineGetAddressStatus
  • TSPI_lineGetCallAddressID
  • TSPI_lineGetCallHubTracking
  • TSPI_lineGetCallIDs
  • TSPI_lineGetCallInfo
  • TSPI_lineGetCallStatus
  • TSPI_lineGetDevCaps
  • TSPI_lineGetDevConfig
  • TSPI_lineGetExtensionID
  • TSPI_lineGetIcon
  • TSPI_lineGetID
  • TSPI_lineGetLineDevStatus
  • TSPI_lineGetNumAddressIDs
  • TSPI_lineHold
  • TSPI_lineMakeCall
  • TSPI_lineMonitorDigits
  • TSPI_lineMonitorMedia
  • TSPI_lineMonitorTones
  • TSPI_lineMSPIdentify
  • TSPI_lineNegotiateExtVersion
  • TSPI_lineNegotiateTSPIVersion
  • TSPI_lineOpen
  • TSPI_linePark
  • TSPI_linePickup
  • TSPI_linePrepareAddToConference
  • TSPI_lineReceiveMSPData
  • TSPI_lineRedirect
  • TSPI_lineReleaseUserUserInfo
  • TSPI_lineRemoveFromConference
  • TSPI_lineSecureCall
  • TSPI_lineSelectExtVersion
  • TSPI_lineSendUserUserInfo
  • TSPI_lineSetAppSpecific
  • TSPI_lineSetCallData
  • TSPI_lineSetCallHubTracking
  • TSPI_lineSetCallParams
  • TSPI_lineSetCallQualityOfService
  • TSPI_lineSetCallTreatment
  • TSPI_lineSetCurrentLocation
  • TSPI_lineSetDefaultMediaDetection
  • TSPI_lineSetDevConfig
  • TSPI_lineSetLineDevStatus
  • TSPI_lineSetMediaControl
  • TSPI_lineSetMediaMode
  • TSPI_lineSetStatusMessages
  • TSPI_lineSetTerminal
  • TSPI_lineSetupConference
  • TSPI_lineSetupTransfer
  • TSPI_lineSwapHold
  • TSPI_lineUncompleteCall
  • TSPI_lineUnhold
  • TSPI_lineUnpark


TSPI_lineAccept

The TSPI_lineAccept function accepts the specified offered call. It can optionally send the specified user-user information to the calling party.

LONG TSPIAPI TSPI_lineAccept(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be accepted. The call state of hdCall can be offering.
lpsUserUserInfo
A pointer to a null-terminated Unicode string containing user-user information to be sent to the remote party as part of the call accept. This pointer is NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

Return Values

Returns dwRequestID if the function is completed asynchronously or an error number if an error occurs. The lResult parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_OPERATIONUNAVAIL.

Remarks

The TSPI_lineAccept function is used in telephony environments (such as ISDN) that allow alerting associated with incoming calls to be separate from the initial offering of the call. When a call comes in, the call is first offered. For some small time duration, the client application may have the option to reject the call using TSPI_lineDrop, redirect the call to another station using TSPI_lineRedirect, answer the call using TSPI_lineAnswer, or accept the call using TSPI_lineAccept. After a call has been successfully accepted, alerting at both the called and calling device begins, and typically the call state transitions to the accepted state. The service provider must set the flag LINEADDRCAPFLAGS_ACCEPTTOALERT in the dwAddrCapFlags member of the LINEADDRESSCAPS data structure if the application must call TSPI_lineAccept for alerting to begin.

To TAPI, alerting is reported using the LINE_LINEDEVSTATE message with the ringing indication.

TSPI_lineAccept may also be supported by non-ISDN service providers. The call state transition to the accepted state can be used by other of the TAPI clients as an indication that some application has claimed responsibility for the call and has presented the call to the user.

The client application has the option to send user-user information at the time of the accept. Even if user-user information can be sent, often no guarantees are made that the network will deliver this information to the calling party. The client application may consult a line's device capabilities to determine whether call accept is available.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINE_LINEDEVSTATE, LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineAnswer, TSPI_lineDrop, TSPI_lineOpen, TSPI_lineRedirect


TSPI_lineAddToConference

The TSPI_lineAddToConference function adds the call specified by hdConsultCall to the conference call specified by hdConfCall.

LONG TSPIAPI TSPI_lineAddToConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdConfCall,
  HDRVCALL hdConsultCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdConfCall
The handle to the conference call. The call state of hdConfCall can be onHoldPendingConference or onHold.
hdConsultCall
The handle to the call to be added to the conference call. This call cannot be either a parent of another conference or a participant in any conference. Depending on the device capabilities indicated in LINEADDRESSCAPS, the hdConsultCall parameter may not necessarily have been established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference. The call state of hdConsultCall can be connected, onHold, proceeding, or ringback.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_CONFERENCEFULL, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

The servicer provider returns LINEERR_INVALCALLHANDLE if hdConsultCall is a parent of another conference or already a participant in a conference, or hdConsultCall cannot be added for other reasons, such as it must have been established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference.

Note The call handle of the added party remains valid after adding the call to a conference; typically, its state changes to conferenced while the state of the conference call becomes connected. The handle to an individual participating call can be used later to remove that party from the conference call using TSPI_lineRemoveFromConference.

The call states of the calls participating in a conference are not independent. For example, when dropping a conference call, all participating calls can automatically become idle. TAPI can consult the line's device capabilities to determine what form of conference removal is available. TAPI or its client applications should track the LINE_CALLSTATE messages to determine what happened to the calls involved.

The conference call is established either through TSPI_lineSetupConference or TSPI_lineCompleteTransfer. Typically, the call added to a conference is established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference. Some switches may allow adding of an arbitrary call to conference, and such a call may have been set up using TSPI_lineMakeCall and be on (hard) hold. All calls that are part of a conference must exist on the same open line.

Any monitoring (media, tones, digits) on a conference call applies only to the hdConfCall parameter, not to the individual participating calls.

This function has no restrictions based on privilege as in the corresponding function at the TAPI level. There is no explicit requirement for the service provider to track the relationships between the "parent" conference call and its participants, because there is no TSPI correspondence to the TAPI function. Many service providers may find it necessary to track these relationships internally to implement the other conference call management functions.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_CALLSTATE, TSPI_lineCompleteTransfer, TSPI_linePrepareAddToConference, TSPI_lineRemoveFromConference, TSPI_lineSetupConference


TSPI_lineAnswer

The TSPI_lineAnswer function answers the specified offering call.

LONG TSPIAPI TSPI_lineAnswer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be answered. The call state of hdCall can be offering or accepted.
lpsUserUserInfo
A pointer to a null-terminated string containing user-user information to be sent to the remote party at the time of answering the call. If this pointer is NULL, it indicates that no user-user information is to be sent. User-user information is only sent if supported by the underlying network (as indicated in LINEDEVCAPS).
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INUSE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG.

Remarks

When a new call arrives, the service provider sends TAPI a LINE_NEWCALL message to exchange handles for the call. The service provider follows this with a LINE_CALLSTATE message to inform TAPI and its client applications of the call's state. A client application typically answers the call using TSPI_lineAnswer. Typically, after the call is successfully answered, the call transitions to the connected state.

In some telephony environments (like ISDN) where user alerting is separate from call offering, TAPI and its client applications may have the option to first accept a call prior to answering, or instead to reject or redirect the offering call.

If a call is offered at the time another call is already active, the new call is connected to by invoking TSPI_lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold. The appropriate LINE_CALLSTATE messages are used to report state transitions to TAPI about both calls.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINE_NEWCALL, LINEDEVCAPS


TSPI_lineBlindTransfer

The TSPI_lineBlindTransfer function performs a blind or single-step transfer of the specified call to the specified destination address.

LONG TSPIAPI TSPI_lineBlindTransfer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be transferred. The call state of hdCall can be connected.
lpszDestAddress
A pointer to a null-terminated Unicode string identifying where the call is to be transferred to. The destination address uses the standard dialable number format.
dwCountryCode
The country code of the destination. The implementation should use this to select the call progress protocols for the destination address. If a value of 0 is specified, the service provider should use a default. TAPI does not validate dwCountryCode when this function is called.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_ADDRESSBLOCKED, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCOUNTRYCODE.

Remarks

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

Blind transfer differs from a consultation transfer in that no consultation call is made visible to TAPI. Typically, after the blind transfer successfully completes, the specified call is cleared from the line it was on and transitions to the idle state. The service provider's call handle must remain valid after the transfer has completed. TAPI causes this handle to be invalidated when it is no longer interested in the transferred call using TSPI_lineCloseCall.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineCloseCall


TSPI_lineClose

The TSPI_lineClose function closes the specified open line device after completing or aborting all outstanding calls and asynchronous operations on the device.

LONG TSPIAPI TSPI_lineClose(
  HDRVLINE hdLine
);

Parameters

hdLine
The service provider's handle to the line to be closed. After the line is successfully closed, this handle is no longer valid.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider must report completion for every asynchronous operation. If TSPI_lineClose is called for a line on which there are outstanding asynchronous operations, the operations are reported complete with an appropriate result or error code before this procedure returns.

A similar requirement exists for active calls on the line. Outstanding operations must be reported complete with appropriate result or error codes. Active calls must also be dropped, if required, and if this behavior was indicated by the LINEDEVCAPFLAGS_CLOSEDROP bit in the LINEDEVCAPS structure.

After this procedure returns, the service provider must report no further htCall on the line or calls that were on the line. The service provider's handles for the line and calls on the line become "invalid."

The service provider must relinquish nonsharable resources it reserves while the line is open. For example, closing a line accessed through a comm port and modem should result in closing the comm port, making it once again available for use by other applications.

The service provider does not issue the LINE_LINEDEVSTATE message in response to this function invocation because the line closes and there is no longer any interest in its state changes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, LINEDEVCAPS


TSPI_lineCloseCall

The TSPI_ lineCloseCall function deallocates the call after completing or aborting all outstanding asynchronous operations on the call.

LONG TSPIAPI TSPI_lineCloseCall(
  HDRVCALL hdCall
);

Parameters

hdCall
The service provider's handle to the call to be closed. After the call is successfully closed, this handle is no longer valid. The call state can be any state.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider must report completion for asynchronous operations. If TSPI_lineCloseCall is called for a call on which there are outstanding asynchronous operations, the operations should be reported complete with an appropriate result or error code before this procedure returns. After this procedure returns, the service provider must report no further events on the call. The service provider's handles for the line and calls on the line become "invalid."

TAPI does not call TSPI_lineCloseCall if a service provider synchronously returns an error from a call to the TSPI_lineMakeCall function. But TAPI does call TSPI_lineCloseCall if the service provider returns an error from the asynchronous operation initiated by TSPI_lineMakeCall.

If there is an active call on the line at the time of TSPI_lineCloseCall, the call must be dropped if this behavior is indicated by the LINEDEVCAPFLAGS_CLOSEDROP bit in the LINEDEVCAPS structure.

If the service provider can determine that there is another agent sharing control of the call, such as in a party line situation with a separate handset, the service provider simply lets control of the call pass to the other agent rather than forcibly dropping it.

This function should always succeed except in extraordinary circumstances. Most callers will probably ignore the return code because they will be unable to compensate for any error that occurs. The specified return values are more advisory for development diagnostic purposes than anything else.

This function is called when the last application with a handle to this call executes lineDeallocateCall.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINEDEVCAPS, TSPI_lineMakeCall


TSPI_lineCloseMSPInstance

The TSPI_lineCloseMSPInstance function directs the TAPI 3.0 DLL to close a media service provider (MSP) call instance. This function requires TAPI 3.0 version negotiation.

LONG TSPIAPI TSPI_lineCloseMSPInstance(
    HDRVMSPLINE hdMSPLine
);

Parameters

hdMSPLine
Pointer to the TSP handle for the MSP call.

Return Values

LINEERR_INVALPOINTER, NOERROR.

Remarks

An MSP instance is associated with a particular application. If multiple applications are running, each TSP line may have multiple MSP instances.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

About The Media Service Provider (MSP), TSPI_lineMSPIdentify, TSPI_lineCreateMSPInstance, TSPI_lineReceiveMSPData, LINEDEVCAPS


TSPI_lineCompleteCall

The TSPI_lineCompleteCall function is used to specify how a call that cannot be connected normally is to be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer.

LONG TSPIAPI TSPI_lineCompleteCall(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPDWORD lpdwCompletionID,
  DWORD dwCompletionMode,
  DWORD dwMessageID
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call whose completion is requested. The call state of hdCall can be busy, ringback, or proceeding.
lpdwCompletionID
A pointer to a DWORD-sized memory location where the service provider writes a completion identifer. This uniquely identifies a completion request in progress on the line that contains the hdCall. In particular, a completion identifier becomes invalid after the request completes or is canceled using the TSPI_lineUncompleteCall function. The service provider is free to reuse the completion identifier as soon as it becomes invalid.
dwCompletionMode
The way in which the call is to be completed. This parameter uses one and only one of the LINECALLCOMPLMODE_ constants.
dwMessageID
The message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This identifier selects the message from a small number of predefined messages. This parameter is not validated by TAPI when this function is called.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLCOMPLMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_COMPLETIONOVERRUN, LINEERR_INVALMESSAGEID.

Remarks

This function is considered complete when the request is accepted by the network or switch; not when the request is fully completed in the way specified. When the called station or network enters a state where the call can be completed as requested, the service privider must send a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record lists the reason for the call as CALLCOMPLETION and provides the completion identifier as well. It is possible to have multiple call completion requests outstanding at any given time; the maximum number is device dependent. The completion identifier is also used to refer to each individual request so requests can be canceled by calling TSPI_lineUncompleteCall.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINECALLINFO, LINECALLCOMPLMODE_ Constants, LINECALLSTATUS, TSPI_lineGetCallInfo, TSPI_lineUncompleteCall


TSPI_lineCompleteTransfer

The TSPI_lineCompleteTransfer function completes the transfer of the specified call to the party connected in the consultation call. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the original call handle is changed to a conference call. Otherwise, the service provider should send call state messages changing the calls to idle.

LONG TSPIAPI TSPI_lineCompleteTransfer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  HDRVCALL hdConsultCall,
  HTAPICALL htConfCall,
  LPHDRVCALL lphdConfCall,
  DWORD dwTransferMode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be transferred. The call state of hdCall can be onHoldPendingTransfer.
hdConsultCall
A handle to the call that represents a connection to the destination of the transfer. The call state of hdConsultCall can be connected, ringback, busy, or proceeding.
htConfCall
This parameter is only valid if dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE. The service provider must save this parameter value and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call. Otherwise this parameter is ignored.
lphdConfCall
A pointer to an HDRVCALL representing the service provider's identifier for the call. This parameter is only valid if dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE. The service provider must fill this location with its handle for the new conference call before returning from this function.
dwTransferMode
Specifies how the initiated transfer request is to be resolved. This parameter uses one of the LINETRANSFERMODE_ constants.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

This function completes the transfer of the original call, hdCall, to the party currently connected through hdConsultCall. The consultation call is typically dialed on the consultation call allocated as part of TSPI_lineSetupTransfer, but it can be any call to which the switch is capable of transferring hdCall.

The transfer request can be resolved either as a transfer or as a three-way conference call. When resolved as a transfer, the parties connected through hdCall and hdConsultCall are connected to each other, and both hdCall and hdConsultCall transition to the idle state.

When resolved as a conference, all three parties enter into a conference call. Both existing call handles remain valid, but transition to the conferenced state. A conference call handle is created and returned, and it transitions to the connected state.

It may also be possible to perform a blind transfer of a call using TSPI_lineBlindTransfer.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT message for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEEVENT, LINETRANSFERMODE_ Constants, TSPI_lineBlindTransfer, TSPI_lineCloseCall, TSPI_lineSetupTransfer


TSPI_lineConditionalMediaDetection

The TSPI_lineConditionalMediaDetection function is invoked by TAPI whenever a client application uses LINEMAPPER as the dwDeviceID in a lineOpen function call to request that lines be scanned to find one that supports the desired media types and call parameters. TAPI scans based on the union of the desired media type and the other media types currently being monitored on the line, to give the service provider the opportunity to indicate if it cannot simultaneously monitor for all of the requested media types. If the service provider can monitor for the indicated set of media types and support the capabilities indicated in lpCallParams, it replies with a success indication. It leaves the active media monitoring modes for the line unchanged.

LONG TSPIAPI TSPI_lineConditionalMediaDetection(
  HDRVLINE hdLine,
  DWORD dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hdLine
The service provider's handle to the line on which media monitoring and parameter capabilities are to be set.
dwMediaModes
The media type(s) currently of interest to the calling application. This parameter uses one of the LINEMEDIAMODE_ constants.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. It describes the call parameters that the line device should be able to provide. The only relevant fields of lpCallParams for the purposes of this test are the following:

dwBearerMode

dwMinRate

dwMaxRate

dwMediaMode

dwCallParamFlags

dwAddressMode

If dwAddressMode is LINEADDRESSMODE_ADDRESSID, any address on the line is acceptable. If dwAddressMode is LINEADDRESSMODE_DIALABLEADDR, indicating that a specific originating address (phone number) is searched for, or if it is a provider-specific extension, then dwOrigAddressSize/Offset and the portion of the variable part they refer to are also relevant. If dwAddressMode is a provider-specific extension, additional information can be contained in the dwDeviceSpecific variably sized field. All other fields are irrelevant to the function.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONUNAVAIL.

Remarks

A TAPI lineOpen function that specifies a device identifier of LINEMAPPER typically results in calling this procedure for multiple line devices to hunt for a suitable line, possibly also opening as-yet unopened lines. A success result indicates that the line is suitable for the calling application's requirements.

Note The media monitoring modes demanded at the TSPI level are the union of monitoring modes demanded by multiple applications at the TAPI level. As a consequence, it is most common for multiple media type flags to be set simultaneously at this level. The service provider must test to determine if it can support at least the specified set, regardless of what modes are currently in effect. TAPI ensures that the dwMediaModes parameter has at least one bit set and that no reserved bits are set. It is the service provider's responsibility to do any further validity checks on the media types, such as checking whether any media types are supported by the service provider.

The TSPI_lineConditionalMediaDetection function checks the bits set in the dwCallParamFlags member of the LINECALLPARAMS structure and handles the following cases:

The TSPI_lineConditionalMediaDetection function returns success if passing the same bit values to the TSPI_lineMakeCall function would also return success.

If the SECURE, ORIGOFFHOOK, and DESTOFFHOOK bits are set and the dwAddressMode parameter is LINEADDRESSMODE_ADDRESSID, the function returns success if it can succeed on one or more addresses on the line.

If the SECURE, ORIGOFFHOOK, and DESTOFFHOOK bits are set and the dwAddressMode parameter is LINEADDRESSMODE_DIALABLEADDR, the function returns success if it can succeed on the address identified by the dwOrigAddress parameter.

The service provider returns an error (for example, LINEERR_RESOURCEUNAVAIL) if, at the time this function is called, it is impossible to place a new call on the specified line device (if it would return LINEERR_CALLUNAVAIL or LINEERR_RESOURCEUNAVAIL should TSPI_lineMakeCall be invoked immediately after opening the line).

There is no directly corresponding function at the TAPI level. This procedure corresponds to the test implied for each individual line by the lineOpen procedure when it is called with the device identifier LINEMAPPER.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINECALLPARAMS, LINEMEDIAMODE_ Constants, TSPI_lineMakeCall


TSPI_lineConfigDialog

The TSPI_lineConfigDialog function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_lineConfigDialog.

The TSPI_lineConfigDialog function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device.

LONG TSPIAPI TSPI_lineConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box should be selected. The permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters.)

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The procedure must update the [Windows Telephony] section in the Win.ini file and broadcast the WM_WININICHANGE message if it makes any changes to the Telephon.ini file that would cause a change in the line or address capabilities reported in LINEDEVCAPS or LINEADDRESSCAPS, or if a line device is created or removed.

There is no restriction that this function (TSPI_lineConfigDialog) be called only when the line is closed. However, each provider can impose such a restriction itself. When TSPI_lineConfigDialog is called, the provider could alert the user with the message "The line is in use by one or more applications. You may not change the line configuration while the line is in use" (and return the error message LINEERR_INUSE). However, some configuration may be safe to change "on the fly," particularly those related to media types (such as the modem error control protocol), especially when that media type is not currently in use. The provider could allow those options to be changed while the line is open.

Users should not be allowed to change anything that alters values returned with LINEDEVCAPS or LINEADDRESSCAPS without first forcibly closing the line as a signal that applications must call functions that return these structures in order to have accurate information.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tspi.h.

See Also

LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig


TSPI_lineConfigDialogEdit

The TSPI_lineConfigDialogEdit function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_lineConfigDialogEdit.

The TSPI_lineConfigDialogEdit function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device.

LONG TSPIAPI TSPI_lineConfigDialogEdit(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD dwSize,
  LPVARSTRING lpDeviceConfigOut
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached.
lpszDeviceClass
A pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or points to an empty string, the highest level configuration is selected. The permitted strings are the same as for TSPI_lineGetID.
lpDeviceConfigIn
A pointer to the opaque configuration data structure that was returned by TSPI_lineGetDevConfig (or a previous invocation of TSPI_lineConfigDialogEdit) in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfigIn. This value is returned in the dwStringSize member in the VARSTRING structure returned by TSPI_lineGetDevConfig or a previous invocation of TSPI_lineConfigDialogEdit.
lpDeviceConfigOut
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig (or a future invocation of lineConfigDialogEdit), the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM.

Remarks

This function causes the service provider to display a modal dialog box (attached to hwndOwner) to allow the user to configure parameters related to the line specified by dwDeviceID.

The lpszDeviceClass parameter selects a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter is "tapi/line", "", or NULL to cause the provider to display the highest level configuration for the line.

The difference between this function and TSPI_lineConfigDialog is the source of the parameters to edit and the result of the editing. In TSPI_lineConfigDialog, the parameters edited are those currently in use on the device (or set for use on the next call), and any changes made have (to the maximum extent possible) an immediate impact on any active connection; also, the application must use lineGetDevConfig to fetch the result of parameter changes from TSPI_lineConfigDialog. With TSPI_lineConfigDialogEdit, the parameters to edit are passed in from the application, and the results are returned to the application, with no impact on active connections; the results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, TSPI_lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. However, the output of this function can be passed to TSPI_lineSetDevConfig to affect the current call or next call.

For backward compatibility, this function is not exported by older service providers. TAPI detects this condition and reports LINEERR_OPERATIONUNAVAIL if an application attempts to call this function on an older provider.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tspi.h.

See Also

TSPI_lineConfigDialog, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig, VARSTRING


TSPI_lineCreateMSPInstance

The TSPI_lineCreateMSPInstance function directs the TAPI 3.0 DLL to create a media service provider (MSP) instance for a specific line device. This function returns a TSP handle for the MSP call. This function requires TAPI 3.0 version negotiation.

LONG TSPIAPI TSPI_lineCreateMSPInstance(
    HDRVLINE hdLine,
    DWORD dwAddressID,
    HTAPIMSPLINE htMSPLine,
    LPHDRVMSPLINE lphdMSPLine
);

Parameters

hdLine
The service provider's handle to the line.
dwAddressID
An address on the specified open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
htMSPLine
The TAPI handle for the MSP call.
lphdMSPLine
Pointer to the TSP handle for the MSP call.

Return Values

LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, NOERROR

Remarks

The service provider should save the htMSPLine handle field, to be used when sending LINE_SENDMSPDATA messages to Tapisrv.exe.

An MSP instance is associated with a particular application. If multiple applications are running, each TSP line may have multiple MSP instances.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

About The Media Service Provider (MSP), TSPI_lineMSPIdentify, TSPI_lineReceiveMSPData, TSPI_lineCloseMSPInstance, LINEDEVCAPS


TSPI_lineDevSpecific

The TSPI_lineDevSpecific function is used as a general extension mechanism to enable service providers to provide access to features not described in other operations. The meanings of the extensions are device-specific, and to take advantage of these extensions the application must be fully aware of them.

LONG TSPIAPI TSPI_lineDevSpecific(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The service provider's handle to the line to be operated on.
dwAddressID
The address on the specified line to be operated on. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
hdCall
The service provider's handle to the call to be operated on. This field may have the value NULL. The call state of hdCall is device specific.
lpParams
A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

Additional return values are device specific.

This operation provides a generic parameter profile. The interpretation of the parameter structure is device specific. TAPI always specifies the hdLine parameter. Whether dwAddressID and/or hdCall are expected to be valid is device specific. If specified, they must belong to hdLine. Indications and replies sent back to the application that are device specific use the LINE_DEVSPECIFIC message.

This function is called in direct response to an application calling the TAPI function lineDevSpecific. TAPI translates the hLine and hCall parameters used at the TAPI level to the corresponding hdLine and hdCall parameters used at the TSPI level. The lpParams buffer is passed unmodified.

Note The lpParams data structure should not contain any pointers because they would not be properly translated (thunked) when running a 16-bit application in a 32-bit version of TAPI and vice versa.

A service provider can provide access to device-specific functions by defining parameters for use with this operation. Applications that want to make use of these device-specific extensions should consult the device-specific documentation (in this case meaning vendor-specific) that describes which extensions are defined.

Note An application that relies on device-specific extensions is not portable in working with other service provider environments. Use vendor-specific extensions.

This operation is part of the Extended Telephony services. It only provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated and selected a device-specific extension version.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_DEVSPECIFIC, TSPI_lineNegotiateExtVersion


TSPI_lineDevSpecificFeature

The TSPI_lineDevSpecificFeature function is used as an extension mechanism to enable service providers to provide access to features not described in other operations. The meanings of these extensions are device specific, and taking advantage of these extensions requires TAPI or its client application to be fully aware of them.

LONG TSPIAPI TSPI_lineDevSpecificFeature(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwFeature,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The service provider's handle to the line device.
dwFeature
The feature to invoke on the line device. This parameter uses PHONEBUTTONFUNCTION_ constants.
lpParams
A pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific.
dwSize
The size of the buffer in bytes.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALFEATURE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

Additional return values are device specific.The call state of hdCall is device-specific.

This function provides TAPI applications with phone feature button emulation capabilities. When TAPI invokes this operation on behalf of a client application, it specifies the equivalent of a "button press" event. This method of invoking features is highly device dependent, as the API does not define their meaning. When an application relies on device-specific extensions, the application does not port well to other service provider environments.

This function is called in direct response to an application calling the TAPI lineDevSpecificFeature function. TAPI translates the hLine parameter used at the TAPI level to the corresponding hdLine parameter used at the TSPI level. The lpParams buffer is passed through unmodified.

Note The lpParams data structure should not contain any pointers because they are not properly translated (thunked) when running a 16-bit application in a 32-bit version of TAPI and vice versa.

This operation is part of the Extended Telephony services. It only provides access to a device-specific feature without defining its meaning. This operation is only available if TAPI has successfully negotiated and selected a device-specific extension version.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_DEVSPECIFICFEATURE, PHONEBUTTONFUNCTION_ Constants


TSPI_lineDial

The TSPI_lineDial function dials the specified dialable number on the specified call.

LONG TSPIAPI TSPI_lineDial(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be dialed. The call state of hdCall can be any state except idle and disconnected.
lpszDestAddress
Pointer to a null-terminated Unicode string that specifies the destination to be dialed using the standard dialable number format.
dwCountryCode
The country code of the destination. The implementation uses this to select the call progress protocols for the destination address. If a value of 0 is specified, a default call-progress protocol defined by the service provider is used. TAPI does not validate this parameter when this function is called.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCOUNTRYCODE, LINEERR_DIALBILLING, LINEERR_INVALCALLSTATE, LINEERR_DIALQUIET, LINEERR_ADDRESSBLOCKED, LINEERR_DIALDIALTONE, LINEERR_NOMEM, LINEERR_DIALPROMPT, LINEERR_OPERATIONUNAVAIL.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow dialing.

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

If the service provider returns LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT, it should perform none of the actions otherwise performed by TSPI_lineDial (for example, no partial dialing, and no going offhook). This is because the service provider should pre-scan the number for unsupported characters first.

TSPI_lineDial is used for dialing on an existing call appearance; for example, call handles returned from TSPI_lineMakeCall with NULL as the lpszDestAddress or ending in ';', call handles returned from TSPI_lineSetupTransfer or TSPI_lineSetupConference. TSPI_lineDial can be invoked multiple times in the course of dialing in the case of multistage dialing, if the line's device capabilities permit it.

If the string pointed to by the lpszDestAddress parameter in the previous call to the TSPI_lineMakeCall or TSPI_lineDial function is terminated with a semicolon, an empty string in the current call to TSPI_lineDial indicates that dialing is complete.

Multiple addresses can be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses, and return a single call handle to the aggregate of all calls to the application. All addresses would use the same country code.

Dialing is considered complete after the address has been accepted by the service provider, not after the call is finally connected. Service providers that provide inverse multiplexing may allow multiple addresses to be provided at once. The service provider must send LINE_CALLSTATE messages to TAPI to inform it about the progress of the call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineMakeCall


TSPI_lineDrop

The TSPI_lineDrop function drops or disconnects the specified call. User-user information can optionally be transmitted as part of the call disconnect. This function can be called by the application at any time. When TSPI_lineDrop returns, the call should be idle.

LONG TSPIAPI TSPI_lineDrop(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be dropped. The call state of hdCall can be any state except idle.
lpsUserUserInfo
This pointer is only valid if dwUserUserInfoSize is nonzero. It specifies a pointer to a null-terminated string containing user-user information to be sent to the remote party as part of the call disconnect. This pointer is NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_OPERATIONUNAVAIL.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow the call to be dropped.

When invoking TSPI_lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call may drop all individual participating calls. LINE_CALLSTATE messages are sent to TAPI for all calls whose call state is affected. Typically, a dropped call transitions to the idle state. Invoking TSPI_lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

In situations where the call to be dropped is a consultation call established during transfer or conference call establishment, the original call that was placed in the OnHoldPending state is reconnected to and it typically re-enters the connected call state.

TAPI has the option to send user-user information at the time of the drop. Even if user-user information can be sent, there is no guarantee that the network will deliver this information to the remote party.

Note In various bridged or party line configurations when multiple parties are on the call, TSPI_lineDrop may not actually clear the call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEDEVCAPS, TSPI_lineGetDevCaps


TSPI_lineDropNoOwner

The TSPI_lineDropNoOwner function is obsolete. TAPI no longer automatically drops a call if no initial owner can be identified, in order to accommodate the distributed control of calls across multiple client machines in a client/server environment.


TSPI_lineDropOnClose

The TSPI_lineDropOnClose function is obsolete. TAPI no longer automatically drops a call when the sole owner closes its handle to the line device, in order to accommodate the distributed control of calls across multiple client machines in a client/server environment.


TSPI_lineForward

The TSPI_lineForward function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. This function provides a combination of forward and do-not-disturb features. This function can also cancel specific forwarding currently in effect.

LONG TSPIAPI TSPI_lineForward(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD bAllAddresses,
  DWORD dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD dwNumRingsNoAnswer,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The service provider's handle to the line to be forwarded.
bAllAddresses
Specifies whether all originating addresses on the line or just the one specified is to be forwarded. If TRUE, all addresses on the line are forwarded and dwAddressID is ignored; if FALSE, only the address specified as dwAddressID is forwarded. This parameter is not validated by TAPI when this function is called.
dwAddressID
The address on the specified line whose incoming calls are to be forwarded. This parameter is ignored if bAllAddresses is TRUE. This parameter is not validated by TAPI when this function is called.

An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

lpForwardList
A pointer to a variably sized data structure of type LINEFORWARDLIST that describes the specific forwarding instructions.
dwNumRingsNoAnswer
Specifies the number of rings before an incoming call is considered a "no answer." If dwNumRingsNoAnswer is out of range, the actual value is set to the nearest value in the allowable range. This parameter is not validated by TAPI when this function is called.
htConsultCall
The TAPI handle to a new call, if such a call must be created by the service provider. In some telephony environments, forwarding a call has the side effect of creating a consultation call used to consult the party that is being forwarded to. In such an environment, the service provider creates the new consutation call and must save this value and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call. If no consultation call is created, this value can be ignored by the service provider.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for the call. In telephony environments where forwarding a call has the side effect of creating a consultation call used to consult the party that is being forwarded to, the service provider must fill this location with its handle for the call before this procedure returns. The service provider is permitted to do callbacks regarding the new call before it returns from this procedure. If no consultation call is created, the HDRVCALL must be left NULL.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. This pointer is ignored by the service provider unless lineForward requires the establishment of a call to the forwarding destination (and lphdConsultCall is returned, in which case lpCallParams is optional). If NULL, default call parameters are used. Otherwise, the specified call parameters are used for establishing htConsultCall.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL.

Remarks

The service provider returns LINEERR_INVALPARAM if the specified forward list parameter contains invalid information.

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

The service provider returns success to this function to indicate only that the request is accepted by the service provider, not that forwarding is set up at the switch. A LINE_ADDRESSSTATE (forwarding) message is sent to provide that forwarding is set up at the switch.

Forwarding of the address or addresses remains in effect until this function is called again. The most recent forwarding list replaces any old one in effect. If this function is called, specifying a NULL pointer as lpForwardList, the service provider should cancel any forwarding that is being performed at that time. If a NULL destination address is specified for an entry in the forwarding list, the operation acts as a "do-not-disturb."

Forwarding status of an address may also be affected externally, for example, through administrative actions at the switch, or by a user from another station. It may not be possible for the service provider to be aware of this state change, and may not be able to keep in sync with the forwarding state known to the switch. The provider must always indicate what it knows to be true, and indicate that the forwarding state is unknown otherwise.

Because a service provider may not know the forwarding state of the address with no doubt (that is, it may have been forwarded or unforwarded in an unknown way), TSPI_lineForward succeeds unless it fails to set the new forwarding instructions. In other words, a request that all forwarding be canceled at a time when there is no forwarding in effect succeeds. This is because there is no unforwarding; you can only invoke a new set of forwarding instructions.

The success or failure of this operation does not depend on the previous set of forwarding instructions, and the same is true when setting different forwarding instructions. If necessary, the provider should "unforward everything" prior to setting the new forwarding instructions. Because this may take time in analog telephony environments, a provider may also want to compare the current forwarding with the new one, and only issue instructions to the switch to get to the final state (leaving unchanged forwarding unaffected).

Invoking TSPI_lineForward when LINEFORWARDLIST has dwNumEntries set to zero has the same effect as providing a NULL lpForwardList parameter; it cancels all forwarding currently in effect.

Because the NULL value returned into lphdConsultCall is the only way for TAPI to determine whether the service provider created a consultation call, the service provider cannot use NULL as a call handle.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION reports success. In other words, it must not issue any messages for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_ADDRESSSTATE, LINECALLPARAMS, LINEEVENT, LINEFORWARDLIST


TSPI_lineGatherDigits

The TSPI_lineGatherDigits function initiates the buffered gathering of digits on the specified call. TAPI specifies a buffer in which to place the digits and the maximum number of digits to be collected.

LONG TSPIAPI TSPI_lineGatherDigits(
  HDRVCALL hdCall,
  DWORD dwEndToEndID,
  DWORD dwDigitModes,
  LPWSTR lpsDigits,
  DWORD dwNumDigits,
  LPCWSTR lpszTerminationDigits,
  DWORD dwFirstDigitTimeout,
  DWORD dwInterDigitTimeout
);

Parameters

hdCall
The service provider's handle to the call on which digit gathering is to be performed. The call state of hdCall can be any state except idle.
dwEndToEndID
A unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GATHERDIGITS message is sent. The service provider includes this identifier as one of the parameters in the message.
dwDigitModes
The digit mode(s) that are to be monitored. This parameter uses one or more of the following LINEDIGITMODE_ contants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of the use of rotary pulse sequences. Valid digits for pulse mode are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.
lpsDigits
A pointer to the buffer where detected digits are to be stored as text characters. The service provider may, but is not required to, place digits in the buffer one at a time as they are collected. When the LINE_GATHERDIGITS message is sent, the content of the buffer must be complete. If lpsDigits is specified as NULL the digit gathering currently in progress on the call is canceled and the dwNumDigits parameter is ignored. Otherwise, lpsDigits is assumed to have room for dwNumDigits digits.
dwNumDigits
The number of digits to be collected before a LINE_GATHERDIGITS message is sent to TAPI. The dwNumDigits parameter is ignored when lpsDigits is NULL. This function must return a LINEERR_INVALPARAM if dwNumDigits is zero.
lpszTerminationDigits
Pointer to a null-terminated Unicode string of termination digits as text characters. If one of the digits in the string is detected, that termination digit is appended to the buffer, digit collection is terminated, and the LINE_GATHERDIGITS message is sent to TAPI.

Valid characters for pulse mode are '0' through '9'. Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'. If this pointer is NULL, or if it points to an empty string, the function behaves as though no termination digits were supplied.

dwFirstDigitTimeout
The time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, digit collection is terminated and a LINE_GATHERDIGITS message is sent to TAPI. A single NULL character is written to the buffer, indicating no digits were received and the first digit timeout terminated digit gathering. The call's line device capabilities specifies the valid range for this parameter or indicates that timeouts are not supported. This parameter is not validated by TAPI when this function is called.
dwInterDigitTimeout
The maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, digit collection is terminated and a LINE_GATHERDIGITS message is sent to TAPI. A single NULL character is written to the buffer, indicating that an interdigit timeout terminated digit gathering. The LINEDEVCAPS structure must specify the the valid range for this parameter or indicate that timeouts are not supported. This parameter is not validated by TAPI when this function is called.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.

Remarks

The service provider returns LINEERR_INVALPARAM if the dwNumDigits parameter is invalid.

This function returns zero (success) if digit collection is correctly initiated; not if digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by an Unicode NULL character.

Digit collection can be terminated in the following ways:

  • The requested number of digits may have been collected.
  • One of the digits detected matches a digit in szTerminationDigits before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned.
  • One of the timeouts expires. The dwFirstDigitTimeout expires if the first digit is not received in this time period. The dwInterDigitTimout expires if the second, third, (and so forth) digit is not received within that time period from the previously detected digit, and a partial buffer is returned.
  • Calling this operation again while collection is in progress. The old collection session is terminated and the contents of the old buffer is undefined. To cancel digit gathering without initiating another operation, this operation is invoked with lpsDigits equal to NULL.

Although this function can be invoked in any call state except idle, digits can typically only be gathered while the call is in the connected state.

The LINE_GATHERDIGITS message is normally sent when the digit buffer becomes filled. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled through another TSPI_lineGatherDigits request on the call. Only one gather digits request can be active at a time. The service provider must terminate any outstanding gathering operation with a LINE_GATHERDIGITS message when TSPI_lineGatherDigits is called.

When the operation associated with a call to the TSPI_lineGatherDigits function is canceled (by a subsequent call to the function), the service provider copies any digits collected up to that point to the buffer specified in the original call.

TAPI can use TSPI_lineMonitorDigits to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a LINE_MONITORDIGITS message is sent to TAPI. Both buffered (gather digits) and unbuffered digit detection can be enabled for the same call simultaneously.

The service provider is allowed some variation in the quality of timing it uses for this function, including not doing timings at all. The quality of timing is reported in LINEDEVCAPS, in the members dwGatherDigitsMinTimeout and dwGatherDigitsMaxTimeout.

The corresponding function at the TAPI level does not include the formal parameter dwEndToEndID. At that level, there is no end-to-end marking. TAPI uses end-to-end marking at the TSPI level to distinguish one TSPI_lineGatherDigits request from another.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINEDEVCAPS, LINEDIGITMODE_ Constants, TSPI_lineGetDevCaps, TSPI_lineMonitorDigits


TSPI_lineGenerateDigits

The TSPI_lineGenerateDigits function initiates the generation of the specified digits on the specified call as in-band tones using the specified signaling mode. Invoking this function while digit or tone generation is in progress aborts the current digit or tone generation. Passing a NULL value for lpsDigits generates no new digits.

Note Only one in-band generation request at a time (tone generation or digit generation) can be in progress per call.

LONG TSPIAPI TSPI_lineGenerateDigits(
  HDRVCALL hdCall,
  DWORD dwEndToEndID,
  DWORD dwDigitMode,
  LPCWSTR lpszDigits,
  DWORD dwDuration
);

Parameters

hdCall
The handle to the call on which digit generation is to be done.
dwEndToEndID
This unique request identifier should be stored by the service provider and passed back as dwParam2 to the LINEEVENT procedure when the digit generation is completed.
dwDigitMode
The format to be used for signaling these digits. This parameter uses one and only one of the LINEDIGITMODE_ constants.
lpszDigits
A pointer to a null-terminated Unicode character buffer that contains the digits to be generated. A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined. The line's device capabilities indicate what this duration is. Multiple commas can be used to inject longer pauses. Invalid digits are ignored during the generation, rather than being reported as an error.
dwDuration
Specifies both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of 0 uses a default value. The dwDuration parameter must be within the range specified by MinDialParams to MaxDialParams in LINEDEVCAPS. If out of range, the actual value is set by the service provider to the nearest value in the range. This parameter is not validated by TAPI when this function is called.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

The call state of hdCall can be any state.

The TSPI_lineGenerateDigits function is considered to have completed successfully when the digit generation is successfully initiated; not when all digits are generated.

After all digits in lpsDigits are generated, or after digit generation is aborted or canceled, a LINE_GENERATE message is sent to TAPI.

Note Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call. This implies that if digit generation is currently in progress on a call, invoking either TSPI_lineGenerateDigits or TSPI_lineGenerateTone cancels the digit generation. The service provider must terminate any digit generation in progress when a subsequent TSPI_lineGenerateDigits or TSPI_lineGenerateTone is invoked. Invoking TSPI_lineGenerateDigits with lpszDigits set to NULL cancels any current digit (or tone) generation.

The corresponding function at the TAPI level does not include the formal parameter dwEndToEndID. At that level, there is no end-to-end marking. TAPI uses end-to-end marking at the TSPI level to disambiguate one TSPI_lineGenerateDigits request from another.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_GENERATE, LINEDEVCAPS, LINEDIGITMODE_ Constants, LINEEVENT, TSPI_lineGenerateTone


TSPI_lineGenerateTone

The TSPI_lineGenerateTone function generates the specified tone inband over the specified call. Invoking this function with a zero for dwToneMode aborts any tone generation currently in progress on the specified call. Invoking TSPI_lineGenerateTone or TSPI_lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation in progress and initiates the generation of the newly specified tone or digits.

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL hdCall,
  DWORD dwEndToEndID,
  DWORD dwToneMode,
  DWORD dwDuration,
  DWORD dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameters

hdCall
The service provider's handle to the call on which tone generation is to be performed. The call state of hdCall can be any state except idle.
dwEndToEndID
A unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GENERATE message is sent. The service provider includes this identifier as one of the parameters in the message.
dwToneMode
Defines the tone to be generated. Tones can be either standard or custom. A custom tone is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified by dwDuration for both standard and custom tones. If dwToneMode is set to zero, any digit or tone generation in progress is canceled. This parameter uses one and only one of the LINETONEMODE_ constants.
dwDuration
The duration in milliseconds during which the tone is sustained. A value of 0 for dwDuration uses a default duration for the specified tone. Default values are:

CUSTOM: infinite

RINGBACK: infinite

BUSY: infinite

BEEP: infinite

BILLING: fixed (single cycle)

This parameter is not validated by TAPI when this function is called.

dwNumTones
The number of entries in the lpTones array. This parameter is ignored if dwToneMode is not equal to LINETONEMODE_CUSTOM.
lpTones
A pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter is ignored for noncustom tones. If lpTones is a multifrequency tone, the various tones are played simultaneously.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTONEMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

TSPI_lineGenerateTone returns zero (success) when the tone generation is successfully initiated; not when the generation of the tone is finished. The function allows the inband generation of several predefined tones, such as ringback, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence and volume, if this is supported by the service provider. Because these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When tone generation is complete, or when tone generation is canceled, a LINE_GENERATE message is sent to TAPI.

Note Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call. This implies that if tone generation is currently in progress on a call, invoking either TSPI_lineGenerateDigits or TSPI_lineGenerateTone cancels the tone generation. The service provider must terminate any tone generation in progress when a subsequent TSPI_lineGenerateDigits or TSPI_lineGenerateTone function is invoked.

The corresponding function at the TAPI level does not include the formal parameter dwEndToEndID. At that level, there is no end-to-end marking. TAPI uses end-to-end marking at the TSPI level to distinguish one TSPI_lineGenerateTone request from another.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_GENERATE, LINEGENERATETONE, LINETONEMODE_ Constants, TSPI_lineGenerateDigits


TSPI_lineGetAddressCaps

The TSPI_lineGetAddressCaps function queries the specified address on the specified line device to determine its telephony capabilities.

LONG TSPIAPI TSPI_lineGetAddressCaps(
  DWORD dwDeviceID,
  DWORD dwAddressID,
  DWORD dwTSPIVersion,
  DWORD dwExtVersion,
  LPLINEADDRESSCAPS lpAddressCaps
);

Parameters

dwDeviceID
The line device containing the address to be queried.
dwAddressID
The address on the given line device whose capabilities are to be queried. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. This parameter is not validated by TAPI when this function is called.
dwTSPIVersion
The version number of the Telephony SPI to be used. The high-order word contains the major version number; the low-order word contains the minor version number.
dwExtVersion
The version number of the service-provider specific extensions to be used. This number is zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contain the minor version number. This parameter is not validated by TAPI when this function is called.
lpAddressCaps
A pointer to a variably sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure is filled with address capabilities information.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Remarks

The line device identifiers supported by a particular driver are numbered sequentially starting with the value of dwLineDeviceIDBase that is passed into the TSPI_providerInit function.

The service provider fills in all the members of the LINEADDRESSCAPS data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

After the service provider returns from the TSPI_lineGetAddressCaps function, TAPI sets the dwCallInfoStates and dwCallStates members of the LINEADDRESSCAPS structure as follows:

LINEADDRESSCAPS.dwCallInfoStates |=
    LINECALLINFOSTATE_NUMOWNERINCR |
    LINECALLINFOSTATE_NUMOWNERDECR |
    LINECALLINFOSTATE_NUMMONITORS;

LINEADDRESSCAPS.dwCallStates |= LINECALLSTATE_UNKNOWN;

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINEADDRESSCAPS, TSPI_providerInit


TSPI_lineGetAddressID

The TSPI_lineGetAddressID function returns the address identifier associated with address in a different format on the specified line.

LONG TSPIAPI TSPI_lineGetAddressID(
  HDRVLINE hdLine,
  LPDWORD lpdwAddressID,
  DWORD dwAddressMode,
  LPCWSTR lpsAddress,
  DWORD dwSize
);

Parameters

hdLine
The service provider's handle to the line whose address is to be retrieved.
lpdwAddressID
A pointer to a DWORD-sized memory location where the address identifier is returned.
dwAddressMode
The address mode of the address contained in lpsAddress. The dwAddressMode parameter is allowed to have one and only one of the LINEADDRESSMODE_ constants.
lpsAddress
A pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by the dwAddressMode parameter. If it is LINEADDRESSMODE_DIALABLEADDR, the lpsAddress parameter uses the common dialable number format and is NULL terminated.
dwSize
The size of the address contained in lpsAddress. The parameter dwSize must be set to the length of the string (plus one for the NULL) if LINEADDRESSMODE_DIALABLEADDR is used. If an extended LINEADDRESSMODE is used, the length should match the size of whatever is actually passed in (the DLL checks to be sure it can read the number of bytes specified from the given pointer).

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

This function is used to map a phone number (address) assigned to a line device back to its dwAddressID (in the range from 0 through the number of addresses minus one) that is returned in the line's device capabilities.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINEADDRESSMODE_ Constants


TSPI_lineGetAddressStatus

The TSPI_lineGetAddressStatus function queries the specified address for its current status.

LONG TSPIAPI TSPI_lineGetAddressStatus(
  HDRVLINE hdLine,
  DWORD dwAddressID,
  LPLINEADDRESSSTATUS lpAddressStatus
);

Parameters

hdLine
The service provider's handle to the line containing the address to be queried.
dwAddressID
An address on the given open line device. This is the address to be queried. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. This parameter is not validated by TAPI when this function is called.
lpAddressStatus
A pointer to a variably sized data structure of type LINEADDRESSSTATUS.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider fills in all the members of the LINEADDRESSSTATUS data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINEADDRESSSTATUS


TSPI_lineGetCallAddressID

The TSPI_lineGetCallAddressID function retrieves the address identifier for the indicated call.

LONG TSPIAPI TSPI_lineGetCallAddressID(
  HDRVCALL hdCall,
  LPDWORD lpdwAddressID
);

Parameters

hdCall
The service provider's handle to the call whose address identifier is to be retrieved. The call state of hdCall can be any state.
lpdwAddressID
A pointer to a DWORD into which the service provider writes the call's address identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

If the service provider models lines as "pools" of channel resources and does inverse multiplexing of a call over several address identifiers it should consistently choose one of these address identifiers as the primary identifier reported by this function and in the LINECALLINFO data structure.

This function has no direct correspondence at the TAPI level. It gives TAPI sufficient information to implement the lineGetNewCalls function invoked with the LINECALLSELECT_ADDRESS option.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINECALLINFO


TSPI_lineGetCallHubTracking

The TSPI_lineGetCallHubTracking function returns the current state of CallHub tracking for the service provider. This function requires TAPI 3.0 version negotiation.

LONG TSPIAPI TSPI_lineGetCallHubTracking(
  HDRVLINE hdLine,
  LPLINECALLHUBTRACKINGINFO lpTrackingInfo
);

Parameters

hdLine
The service provider's handle to the call whose call information is to be retrieved. The call state of hdLine can be any state.
lpTrackingInfo
A pointer to the variably sized LINECALLHUBTRACKINGINFO structure. Upon successful completion of the request, this structure is filled with call-related information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

CallHub Tracking, LINECALLHUBTRACKINGINFO


TSPI_lineGetCallIDs

The TSPI_lineGetCallIDs function returns the call identifiers for the service provider. This function requires TAPI 3.0 version negotiation.

LONG TSPIAPI TSPI_lineGetCallIDs(
  HDRVCALL hdCall,
  LPDWORD lpdwAddressID,
  LPDWORD lpdwCallID,
  LPDWORD lpdwRelatedCallID
);

Parameters

hdCall
The service provider's handle to the call whose identifier is needed.
lpdwAddressID
A pointer to the call's address identifier.
lpdwCallID
A pointer to the call's identifier.
lpdwRelatedCallID
A pointer to the identifier of a related call.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL

Remarks

In some telephony environments, the switch or service provider can assign a unique identifier to each call. This allows the call to be tracked across transfers, forwards, or other events. The domain of these call identifiers and their scope is service-provider defined.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

CallHub Tracking, LINECALLHUBTRACKINGINFO


TSPI_lineGetCallInfo

The TSPI_lineGetCallInfo function returns detailed information about the specified call.

LONG TSPIAPI TSPI_lineGetCallInfo(
  HDRVCALL hdCall,
  LPLINECALLINFO lpCallInfo
);

Parameters

hdCall
The service provider's handle to the call whose call information is to be retrieved. The call state of hdCall can be any state.
lpCallInfo
A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call-related information.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The following table indicates which members of the LINECALLINFO data structure are filled in by TAPI and which members are filled in by the service provider. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Member name | TAPI | Service provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
hLine; | X |
dwLineDeviceID; |  | X
dwAddressID; |  | X
dwBearerMode; |  | X
dwRate; |  | X
dwMediaMode; |  | X
dwAppSpecific; |  | X
dwCallID; |  | X
dwRelatedCallID; |  | X
dwCallParamFlags; |  | X
dwCallStates; | X | X
dwMonitorDigitModes; | X |
dwMonitorMediaModes; | X |
DialParams; |  | X
dwOrigin; |  | X
dwReason; |  | X
dwCompletionID; |  | X
dwNumOwners; | X |
dwNumMonitors; | X |
dwCountryCode; |  | X
dwTrunk; |  | X
dwCallerIDFlags; |  | X
dwCallerIDSize; |  | X
dwCallerIDOffset; |  | X
dwCallerIDNameSize; |  | X
dwCallerIDNameOffset; |  | X
dwCalledIDFlags; |  | X
dwCalledIDSize; |  | X
dwCalledIDOffset; |  | X
dwCalledIDNameSize; |  | X
dwCalledIDNameOffset; |  | X
dwConnectedIDFlags; |  | X
dwConnectedIDSize; |  | X
dwConnectedIDOffset; |  | X
dwConnectedIDNameSize; |  | X
dwConnectedIDNameOffset; |  | X
dwRedirectionIDFlags; |  | X
dwRedirectionIDSize; |  | X
dwRedirectionIDOffset; |  | X
dwRedirectionIDNameSize; |  | X
dwRedirectionIDNameOffset; |  | X
dwRedirectingIDFlags; |  | X
dwRedirectingIDSize; |  | X
dwRedirectingIDOffset; |  | X
dwRedirectingIDNameSize; |  | X
dwRedirectingIDNameOffset; |  | X
dwAppNameSize; | X |
dwAppNameOffset; | X |
dwDisplayableAddressSize; | X |
dwDisplayableAddressOffset; | X |
dwCalledPartySize; | X |
dwCalledPartyOffset; | X |
dwCommentSize; | X |
dwCommentOffset; | X |
dwDisplaySize; |  | X
dwDisplayOffset; |  | X
dwUserUserInfoSize; |  | X
dwUserUserInfoOffset; |  | X
dwHighLevelCompSize; |  | X
dwHighLevelCompOffset; |  | X
dwLowLevelCompSize; |  | X
dwLowLevelCompOffset; |  | X
dwChargingInfoSize; |  | X
dwChargingInfoOffset; |  | X
dwTerminalModesSize; |  | X
dwTerminalModesOffset; |  | X
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

TAPI fills in the size and offset fields for the dwAppNameSize/Offset, dwCalledPartySize/Offset, and dwCommentSize/Offset members and updates the value in dwUsedSize to reflect these after calling the service provider.

After the service provider returns from the TSPI_lineGetCallInfo function, TAPI sets the dwCallStates member of the LINECALLINFO structure as follows:

LINECALLINFO.dwCallStates |= LINECALLSTATE_UNKNOWN;

If the service provider models lines as "pools" of channel resources and does inverse multiplexing of a call over several address identifiers, it should consistently choose one of these address identifiers as the primary identifier reported by this function in the LINECALLINFO data structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.


TSPI_lineGetCallStatus

The TSPI_lineGetCallStatus function returns the current status of the specified call.

LONG TSPIAPI TSPI_lineGetCallStatus(
  HDRVCALL hdCall,
  LPLINECALLSTATUS lpCallStatus
);

Parameters

hdCall
The service provider's handle to the call to be queried for its status. The call state of hdCall can be any state.
lpCallStatus
A pointer to a variably sized data structure of type LINECALLSTATUS. This structure is filled with call status information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The following table indicates which members of the LINECALLSTATUS data structure are filled in by the service provider and which members are filled in by TAPI. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Member name | TAPI | Service provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
dwCallState; |  | X
dwCallStateMode; |  | X
dwCallPrivilege; | X |
dwCallFeatures; |  | X
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

TSPI_lineGetCallStatus returns the dynamic status of a call, whereas TSPI_lineGetCallInfo returns primarily static information about a call. Call status information includes the current call state, detailed mode information related to the call while in this state (if any), as well as a list of the available TSPI functions TAPI can invoke on the call while the call is in this state.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINECALLSTATUS, TSPI_lineGetCallInfo


TSPI_lineGetDevCaps

The TSPI_lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device.

LONG TSPIAPI TSPI_lineGetDevCaps(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwExtVersion,
  LPLINEDEVCAPS lpLineDevCaps
);

Parameters

dwDeviceID
The line device to be queried.
dwTSPIVersion
The negotiated TSPI version number. This value has already been negotiated for this device through the TSPI_lineNegotiateTSPIVersion function.
dwExtVersion
The negotiated extension version number. This value has already been negotiated for this device through the TSPI_lineNegotiateExtVersion function. This parameter is not validated by TAPI when this function is called.
lpLineDevCaps
A pointer to a variably sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

Line device identifier numbering for a service provider is sequential from the value set by the dwLineDeviceIDBase parameter that is passed to the TSPI_providerInit function.

The dwExtVersion formal parameter indicates the version number of the requested extension information. If it is zero, no extension information is requested. If it is nonzero, it holds a value that was negotiated for this device with the TSPI_lineNegotiateExtVersion function. The service provider fills in device- and vendor-specific extended information according to the extension version specified.

The service provider fills in all the members of the LINEDEVCAPS data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

The service provider must fill in all members of the LINETERMCAPS data structure or structures embedded in the varying part of the LINEDEVCAPS data structure.

After the service provider returns from the TSPI_lineGetDevCaps function, TAPI sets the dwLinesStates member of the LINEDEVCAPS structure as follows:

LINEDEVCAPS.dwLineStates |=
    LINEDEVSTATE_OPEN |
    LINEDEVSTATE_CLOSE |
    LINEDEVSTATE_REINIT |
    LINEDEVSTATE_TRANSLATECHANGE;

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINEDEVCAPS, LINETERMCAPS, TSPI_lineNegotiateExtVersion, TSPI_lineNegotiateTSPIVersion, TSPI_providerInit


TSPI_lineGetDevConfig

The TSPI_lineGetDevConfig function returns a data structure object, the contents of which are specific to the line (service provider) and device class, giving the current configuration of a device associated one-to-one with the line device.

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to a data structure of type VARSTRING where the device configuration structure of the associated device is returned. Upon successful completion of the request, the service provider fills this data structure with the device configuration. The dwStringFormat member in the VARSTRING structure must be set to STRINGFORMAT_BINARY. If the dwTotalSize member of the VARSTRING structure pointed to by the lpDeviceConfig parameter is greater than or equal to the size of the fixed portion of the structure, the service provider sets the dwNeededSize member to the required size and returns zero.
lpszDeviceClass
A pointer to a null-terminated Unicode string that specifies the device class of the device whose configuration is requested. Valid device class strings are the same as those specified for the TSPI_lineGetID function when it is applied to a line device (dwSelect has the value LINECALLSELECT_LINE).

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Remarks

The call state is device-specific.

This function can be used to retrieve a data structure from the service provider that specifies the configuration of a device associated one-to-one with the line device. The lpszDeviceClass parameter selects which of among possibly several different classes of devices is to have its configuration retrieved. The set of supported classes is restricted to those whose devices correspond one-to-one with the line device. For more information about common device classes, see TSPI Device Classes.

A service provider should typically allow the tapi/line device class under this function. It would retrieve parameters that have "line" scope, such as the list of addresses in this line, the list of physical hardware devices such as COMM ports corresponding to the addresses, maximum number of concurrent calls (if configurable), and so on.

In general, this function does not allow media-related device classes such as mci waveaudio, low level wave, or datamodem device classes, because these usually apply to a particular call or a particular address. Because there can be more than one of these per line device, the identification of the particular call or address simply by the line device identifier parameter in this function would be ambiguous. An exception can be made for call-specific or address-specific device classes in cases where there is class configuration information that applies to the entire line device scope, such as initial defaults, and so on.

There are several reasons why exceptional support for call-specific and address-specific device classes is of only limited value under this function. First, because these classes can be ambiguous on multiple-address/multiple-call service providers, only a subset of service providers support them. Applications are not likely to add a device-specific dependency on the inclusion of these classes in this function. Second, as higher-level media "classes" emerge that implement high-level protocols such as dial-in file system access in terms of low-level transport APIs, configuration for these classes tends toward "instance" scope instead of "class" scope. The high-level media API must supply its own functions to configure call-specific or address-specific instances.

Whatever sort of devices and device classes this function supports, it can potentially affect two kinds of configuration information: permanent and temporary. Permanent information survives across different "opens" of the line, and even across different "inits" of the service provider itself. Temporary information survives only within a unique "open" of the line. When the line is closed, any such temporary information that has been retrieved or set through TSPI_lineSetDevConfig can revert to default or undefined values. The caller can reliably retrieve any temporary configuration only by a sequence such as TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. The caller can reliably set temporary configuration information retrieved by such a sequence through a sequence such as TSPI_lineOpen, TSPI_lineSetDevConfig. The temporary part of configuration remains stable only until the next TSPI_lineConfigDialog, TSPI_lineSetDevConfig, or TSPI_lineClose. The service provider must take care of storing any permanent part of the configuration, typically in an .ini file, and reloading it whenever the service provider is initialized.

The exact format of the data contained within the structure returned by this function is specific to the line and device class API, is undocumented, and is undefined. The structure returned by this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used in TSPI_lineSetDevConfig to restore the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this may work in some instances, it is not guaranteed). A service provider should put items in the data structure to allow it to be checked for consistency to guard against failures due to a client application passing incompatible information.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineClose, TSPI_lineConfigDialog, TSPI_lineGetID, TSPI_lineOpen, TSPI_lineSetDevConfig, VARSTRING


TSPI_lineGetExtensionID

The TSPI_lineGetExtensionID function returns the extension identifier that the service provider supports for the indicated line device.

LONG TSPIAPI TSPI_lineGetExtensionID(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  LPLINEEXTENSIONID lpExtensionID
);

Parameters

dwDeviceID
The line device to be queried.
dwTSPIVersion
An interface version number that was already negotiated for this device using TSPI_lineNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. If the service provider supports provider-specific extensions, it fills this structure with the extension identifier of these extensions. If the service provider does not support extensions, it fills this structure with all zeros. (Therefore, a valid extension identifier cannot consist of all zeros.)

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

This function is typically called by TAPI in response to an application calling the lineNegotiateAPIVersion function. The result returned by the service provider should be appropriate for use in a subsequent call to TSPI_lineNegotiateExtVersion. An extension identifier of all zeros is not a legal extension identifier, because the all-zeros value is used to indicate that the service provider does not support extensions.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineNegotiateExtVersion, TSPI_lineNegotiateTSPIVersion


TSPI_lineGetIcon

The TSPI_lineGetIcon function retrieves a service line device-specific icon to display to the user.

LONG TSPIAPI TSPI_lineGetIcon(
  DWORD dwDeviceID,
  LPCWSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The line device whose icon is requested.
lpszDeviceClass
A pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select an icon specific to that device class. This parameter is optional and can be left NULL, in which case the highest level icon associated with the line device rather than a specified media stream device is selected.

Permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider.

lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The provider should return a handle (in the DWORD pointed to by lphIcon) to an icon resource (obtained from the Win32 LoadIcon function) associated with the specified line.

A provider may choose to support many icons (selected by lpszDeviceClass and/or line number), a single icon (such as for the manufacturer, which would be returned for all TSPI_lineGetIcon requests regardless of the lpszDeviceClass selected), or no icons, in which case it sets the DWORD pointed to by lphIcon to NULL. TAPI examines the handle returned by the provider, and if the provider returns NULL, TAPI substitutes a generic Win32 Telephony icon (the generic "line" icon).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineConfigDialog, TSPI_lineGetID


TSPI_lineGetID

The TSPI_lineGetID function returns a device identifier for the specified device class associated with the selected line, address, or call.

LONG TSPIAPI TSPI_lineGetID(
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  DWORD dwSelect,
  LPVARSTRING lpDeviceID,
  LPCWSTR lpszDeviceClass,
  HANDLE hTargetProcess
);

Parameters

hdLine
The service provider's handle to the line to be queried.
dwAddressID
An address on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. TAPI does not validate this parameter when this function is called.
hdCall
The service provider's handle to the call to be queried.
dwSelect
Specifies whether the device identifier requested is associated with the line, address, or a single call. The dwSelect parameter can have only one of the LINECALLSELECT_ constants.
lpDeviceID
A pointer to the memory location of type VARSTRING where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class (API) for naming devices.
lpszDeviceClass
A pointer to a null-terminated Unicode string that specifies the device class of the device whose identifier is requested. Valid device class strings are those used in the System.ini section to identify device classes (such as COM, Wave, and MCI.)
hTargetProcess
The process handle of the application on behalf of which the TSPI_lineGetID function is invoked. If the information returned in the VARSTRING structure includes a handle for use by the application, the service provider should create or duplicate the handle for the process.

If hTargetProcess is set to INVALID_HANDLE_VALUE, then the application is executing on a remote client system and it is not possible to create a duplicate handle directly. Instead, the VARSTRING structure should contain a UNC name of a network device or other name that the remote client can use to access the device. If this is not possible, then the function should fail.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NODEVICE, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provide returns LINEERR_INVALLINEHANDLE if dwSelect is LINECALLSELECT_LINE or LINECALLSELECT_ADDRESS, and hdLine is invalid.

The service provider returns LINEERR_INVALCALLHANDLE if dwSelect is LINECALLSELECT_CALL and hdCall is invalid.

The service provider should support the tapi/line device class to allow applications to determine the real line device identifier of an opened line. In that case, the variable data returned is the dwDeviceID. For more information about common device class names, see TSPI Device Classes.

A vendor that defines a device-specific media type also needs to define the corresponding device-specific (proprietary) API to manage devices of the media type. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies the vendor and then the media type; for example: "intel/video".

The service provider fills in all the members of the VARSTRING data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

The service provider does not need to be concerned with handling tapi/line and tapi/phone device classes because TAPI handles these for the service provider. Therefore, code for handling these device classes is optional.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineGetDevConfig, TSPI_lineSetDevConfig, VARSTRING


TSPI_lineGetLineDevStatus

The TSPI_lineGetLineDevStatus function queries the specified open line device for its current status. The information returned is global to all addresses on the line.

LONG TSPIAPI TSPI_lineGetLineDevStatus(
  HDRVLINE hdLine,
  LPLINEDEVSTATUS lpLineDevStatus
);

Parameters

hdLine
The service provider's handle to the line to be queried.
lpLineDevStatus
A pointer to a variably sized data structure of type LINEDEVSTATUS. This structure is filled with the line's device status.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The following table indicates which members of the LINEDEVSTATUS data structure are filled in by TAPI and which are filled in by the service provider. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Member name | TAPI | Service provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
dwNumOpens; | X |
dwOpenMediaModes; | X |
dwNumActiveCalls; |  | X
dwNumOnHoldCalls; |  | X
dwNumOnHoldPendCalls; |  | X
dwLineFeatures; |  | X
dwNumCallCompletions; |  | X
dwRingMode; |  | X
dwSignalLevel; |  | X
dwBatteryLevel; |  | X
dwRoamMode; |  | X
dwDevStatusFlags; |  | X
dwTerminalModesSize; |  | X
dwTerminalModesOffset; |  | X
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINEDEVSTATUS, TSPI_lineGetAddressStatus


TSPI_lineGetNumAddressIDs

The TSPI_lineGetNumAddressIDs function retrieves the number of address identifiers supported on the indicated line.

LONG TSPIAPI TSPI_lineGetNumAddressIDs(
  HDRVLINE hdLine,
  LPDWORD lpdwNumAddressIDs
);

Parameters

hdLine
The handle to the line for which the number of address identifiers is to be retrieved.
lpdwNumAddressIDs
A pointer to a DWORD. The location is filled with the number of address identifiers supported on the indicated line. The value is one or larger.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

This function is called by TAPI in response to an application calling lineSetNumRings, lineGetNumRings, or lineGetNewCalls. TAPI uses the retrieved value to determine if the specified address identifier is within the range supported by the service provider.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

lineSetNumRings, lineGetNumRings, lineGetNewCalls


TSPI_lineHold

The TSPI_lineHold function places the specified call on hold.

LONG TSPIAPI TSPI_lineHold(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be placed on hold. The call state of hdCall can be connected.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The call on hold is temporarily disconnected, allowing TAPI to use the line device for making or answering other calls. TSPI_lineHold performs a hard hold of the specified call, as opposed to a consultation call. A call on hard hold typically cannot be transferred or included in a conference call, whereas a consultation call can. Consultation calls are initiated using TSPI_lineSetupTransfer, TSPI_lineSetupConference, or TSPI_linePrepareAddToConference.

After a call is successfully placed on hold, the call state typically transitions to onHold. A held call is retrieved through TSPI_lineUnhold. While a call is on hold, the service provider can send LINE_CALLSTATE messages about state changes of the held call. For example, if the held party hangs up, the call state can transition to disconnected, and the service provider can send a LINE_CALLSTATE message indicating the new state.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineSetupConference, TSPI_lineSetupTransfer, TSPI_lineUnhold


TSPI_lineMakeCall

The TSPI_lineMakeCall function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  HTAPICALL htCall,
  LPHDRVCALL lphdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which the new call is to be originated.
htCall
The TAPI handle to the new call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.
lphdCall
A pointer to a call handle. The service provider must fill this location with its handle for the call before this procedure returns. This handle is ignored by TAPI if the function results in an error.
lpszDestAddress
Pointer to a null-terminated Unicode string that specifies the destination address. This follows the standard dialable number format. This pointer can be specified as NULL for non-dialed addresses (as with a hot phone, which always automatically connects to a predefined number) or when all dialing is performed using TSPI_lineDial. In the latter case, TSPI_lineMakeCall allocates an available call appearance that would typically remain in the dialtone state until dialing begins. Service providers that have inverse multiplexing capabilities can allow an application to specify multiple addresses at once.
dwCountryCode
The country code of the called party. If a value of 0 is specified, a default is used by the implementation.
lpCallParams
A pointer to a LINECALLPARAMS structure. This structure allows TAPI to specify how it wants the call to be set up. If NULL is specified, a default 3.1kHz voice call is established, and an arbitrary origination address on the line is selected. This structure selects elements such as the call's bearer mode, data rate, expected media type, origination address, blocking of caller ID information, and dialing parameters.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling TSPI_lineGetLineDevStatus updates the information in LINEDEVSTATUS.)

If the service provider returns LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT, it should perform none of the actions otherwise performed by TSPI_lineMakeCall. For example, no partial dialing, and no going offhook. This is because the service provider should pre-scan the number for unsupported characters first.

After TSPI_lineMakeCall returns a SUCCESS reply callback message to the application, the service provider must send LINE_CALLSTATE messages to the lpfnEventProc passed in TSPI_lineOpen to notify TAPI about the progress of the call. A typical reported sequence may be dial tone, dialing, proceeding, ringback, and connected; The first state reported is not necessarily LINECALLSTATE_DIALTONE. The service provider chooses how many of these states are reported. It is recommended that as many as possible are sent, so that applications can take appropriate actions.

The service provider initially does media monitoring on the new call for at least the set of media types that were monitored for on the line.

If the dial string is NULL, the service provider takes the line to the dialtone state (for a Comm-based service provider, this would involve ATD) and send a call-state message indicating LINECALLSTATE_DIALTONE.

If the dial string ends in ';' (a semicolon), the service provider dials the partial number and sends the LINECALLSTATE_DIALING message. This call is completed by calls to TSPI_lineDial.

If the dial string contains characters (W, @, $, ?) that are not supported by the service provider, the service provider must scan the dial string and return (synchronously) an error corresponding to the first invalid character.

If the LINECALLPARAMFLAGS_IDLE flag is set, the service provider must check the current line status (the equivalent of going off-hook and sensing dial tone). If this IDLE flag is set and there is no dial tone, the function fails with the error LINEERR_CALLUNAVAIL. If the IDLE flag is not set, or there is a dial tone, the dialing can continue.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. It must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINECALLPARAMS, LINEEVENT, TSPI_lineDial, TSPI_lineDrop


TSPI_lineMonitorDigits

The TSPI_lineMonitorDigits function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode(s) is detected, a LINE_MONITORDIGITS message is sent to the application by TAPI, indicating which digit is detected.

LONG TSPIAPI TSPI_lineMonitorDigits(
  HDRVCALL hdCall,
  DWORD dwDigitModes
);

Parameters

hdCall
The handle to the call on which digits are to be detected. The call state of hdCall can be any state except idle or disconnected.
dwDigitModes
The digit mode(s) that are to be monitored. A dwDigitModes parameter with a value of 0 cancels digit monitoring. The dwDigitModes parameter can have one of the LINEDIGITMODE_ constants.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

This function returns zero (success) when digit monitoring is correctly initiated, not when digit monitoring is terminated. Digit monitoring remains in effect until it is explicitly disabled by a call to TSPI_lineMonitorDigits with dwDigitModes set to zero, or until the call transitions to idle. The function must return zero when digit monitoring is canceled (that is, when the dwDigitModes parameter is zero). The service provider must terminate digit monitoring when the call goes idle. TAPI does not spontaneously call TSPI_lineMonitorDigits to terminate monitoring.

Although this function can be invoked in any call state, digits typically are detected only while the call is in the connected state.

Each time a digit is detected, the service provider sends a LINE_MONITORDIGITS message to TAPI, passing the detected digit as a parameter. If both LINEDIGITMODE_DTMF and LINEDIGITMODE_DTMFEND are set in dwDigitModes, the two LINE_MONITORDIGITS messages are sent for each digit.

TAPI can use TSPI_lineMonitorDigits to enable or disable unbuffered digit detection. It can use TSPI_lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINEDEVCAPS, LINEDIGITMODE_ Constants, TSPI_lineGatherDigits, TSPI_lineGetDevCaps, TSPI_lineSetMediaControl


TSPI_lineMonitorMedia

The TSPI_lineMonitorMedia function enables and disables the detection of media types on the specified call. When a media type is detected, a LINE_MONITORMEDIA message is sent to TAPI.

LONG TSPIAPI TSPI_lineMonitorMedia(
  HDRVCALL hdCall,
  DWORD dwMediaModes
);

Parameters

hdCall
The handle to the call for which media monitoring is to be set. The call state of hdCall can be any state except idle.
dwMediaModes
The media types to be monitored. The dwMediaModes parameter can have one of the LINEMEDIAMODE_ constants.

A value of 0 cancels all media type monitoring.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

The service provider returns LINEERR_INVALMEDIAMODE if the list of media types to be monitored contains invalid information.

This function returns zero (success) when media type monitoring has been correctly initiated, not when media type monitoring has terminated. Media monitoring for a given media type remains in effect until it is explicitly disabled by calling TSPI_lineMonitorMedia with a dwMediaModes parameter with the media type set to zero, or until the call transitions to idle.

TSPI_lineMonitorMedia is primarily an event reporting mechanism. The media type of a call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media type. Only TAPI or a client application can change a call's indicated media type using TSPI_lineSetMediaMode. The actual use of a particular media type occurs through separate media stream APIs (such as Comm or WAVE).

Default media monitoring performed by the service provider for a new call appearance corresponds to the union of all media types specified by TSPI_lineSetDefaultMediaDetection. Shortly after a new call is established, TAPI typically calls TSPI_lineMonitorMedia to reduce the set of media types detected and reported for this call to the union of all media types desired by the call's client applications.

The service provider must cancel media monitoring when a call goes idle. TAPI must compute the union of media types desired by all clients, and pass the result to this function. The service provider uses the set passed to this function by TAPI.

Although this function can be invoked in any call state, a call's media type can typically only be detected while the call is in certain call states. These states can be device specific. For example, in ISDN a message can indicate the media type of the media stream before the media stream exists. Similarly, distinctive ringing or the called ID information about the call can be used to identify the media type of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media type by filtering of the media stream. Because filtering of a call's media stream implies a computational overhead, TAPI typically uses this procedure to disable media monitoring when it is not required.

Because media-mode detection enabled by TSPI_lineMonitorMedia is implemented as a read-only operation of the call's media stream, it is not disruptive. No signals are sent on the line as a result of setting TSPI_lineMonitorMedia.

Regarding the passed media type, TAPI guarantees that there are no reserved bits set. The service provider must perform any further validity checks on the media types, such as checking whether any media types are indeed supported by the service provider.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_MONITORMEDIA, LINECALLINFO, LINEDEVCAPS, LINEMEDIAMODE_ Constants TSPI_lineConditionalMediaDetection, TSPI_lineGetDevCaps, TSPI_lineSetDefaultMediaDetection, TSPI_lineSetMediaControl, TSPI_lineSetMediaMode


TSPI_lineMonitorTones

The TSPI_lineMonitorTones function enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is sent to the client application through TAPI.

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL hdCall,
  DWORD dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD dwNumEntries
);

Parameters

hdCall
The handle to the call for which tone detection is to be done. The call state of hdCall can be any state except idle.
dwToneListID
The unique identifier for this tone list. Several tone lists can be outstanding at one time. The service provider must replace any old list having the same dwToneListID with the new tone list. If lpToneList is NULL, the tone list with dwToneListID is simply dropped. In any case, other tone lists with different dwToneListIDs are kept unchanged.
lpToneList
A list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an application-defined tag field that is used to identify individual tones in the list for the purpose of reporting a tone detection. Tone monitoring in progress is canceled or changed by calling this operation with either NULL for lpToneList or with another tone list. The service provider must copy the tone list into its own memory for later reference, rather than simply retaining the pointer into application memory.
dwNumEntries
The number of entries in lpToneList. The dwNumEntries parameter is ignored if lpToneList is NULL. TAPI does not validate this parameter when this function is called.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

Remarks

This function returns zero (success) when tone monitoring is correctly initiated, not when tone monitoring is terminated. As with media monitoring, tone monitoring remains in effect for a given tone list until that tone list is explicitly disabled by calling TSPI_lineMonitorTones with the same dwToneListID and another tone list (or a NULL tone list), or until the call transitions to idle.

Although this function can be invoked in any call state except idle, tones can typically only be detected while the call is in the connected state. Tone detection usually requires computational resources. Depending on the service provider and other activities that compete for such resources, the number of tones that can be detected can vary over time. Also, an equivalent amount of resources can be consumed for monitoring a single triple frequency tone versus three single frequency tones. If resources are overcommitted, the service provider returns LINEERR_RESOURCEUNAVAIL.

The service provider monitors for all tones in all tone lists concurrently. When a tone is detected, each matching tone from each tone list is reported separately using a LINE_MONITORTONE message. Each tone report includes both the tone list identifier and the application-specific tag. Some service providers may not be able to discriminate very close tones, so that multiple matches may be reported even for tones whose descriptions are not strictly identical.

Note TSPI_lineMonitorTones is also used to detect silence. Silence is specified as a tone with all zero frequencies.

The corresponding function at the TAPI level does not include a dwToneListID parameter. The inclusion of this parameter at the TSPI interface allows TAPI to forward the union of all tone monitoring lists from all applications to the service provider, while still retaining the ability to filter and forward the tone detection events according to application. This gives service-provider designers the maximum flexibility to determine the degree to which they can discriminate very close tones, because TAPI makes no assumptions about what tone descriptions are considered identical.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_MONITORTONE, LINEDEVCAPS, LINEMONITORTONE, TSPI_lineGetDevCaps, TSPI_lineSetMediaControl


TSPI_lineMSPIdentify

The TSPI_lineMSPIdentify function determines the associated MSP CLSID for every line. This function requires TAPI 3.0 version negotiation.

LONG TSPIAPI TSPI_lineMSPIdentify(
  DWORD dwDeviceID,
  GUID *pCLSID
 );

Parameters

dwDeviceID
The line device whose CLSID is requested.
pCLSID
The TSP fills in the CLSID of the MSP to be created for the line device indicated in dwDeviceID.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL

Remarks

Note that TAPI 3.0 calls TSPI_lineMSPIdentify only if the LINEDEVCAPFLAGS_MSP flag is set in the TSP. (You can set LINEDEVCAPFLAGS_constants in the dwDevCapFlags member of the LINEDEVCAPS structure.)

If the device does not have an associated MSP, the TSP returns LINEERR_OPERATIONUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

About The Media Service Provider (MSP), TSPI_lineReceiveMSPData, TSPI_lineCreateMSPInstance, TSPI_lineCloseMSPInstance, LINEDEVCAPS


TSPI_lineNegotiateExtVersion

The TSPI_lineNegotiateExtVersion function returns the highest extension version number the service provider can operate under for this device, given the range of possible extension versions.

LONG TSPIAPI TSPI_lineNegotiateExtVersion(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

dwDeviceID
Identifies the line device for which interface version negotiation is to be performed. The value INITIALIZE_NEGOTIATION may not be used for this function.
dwTSPIVersion
An interface version number that has already been negotiated for this device using TSPI_lineNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
dwLowVersion
The lowest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. TAPI does not validate this parameter when this function is called.
dwHighVersion
The highest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. TAPI does not validate this parameter when this function is called.
lpdwExtVersion
A pointer to a DWORD. Upon a successful return from this function, the service provider fills this location with the highest extension version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns LINEERR_INCOMPATIBLEEXTVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

This function can be called before or after the device is opened by TAPI. If the device is currently open and has an extension version selected, the function gives that version number if it is within the requested range. If the selected version number is outside the requested range, the function returns LINEERR_INCOMPATIBLEEXTVERSION.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

INITIALIZE_NEGOTIATION, TSPI_lineNegotiateTSPIVersion


TSPI_lineNegotiateTSPIVersion

The TSPI_lineNegotiateTSPIVersion function returns the highest SPI version the service provider can operate under for this device, given the range of possible SPI versions.

LONG TSPIAPI TSPI_lineNegotiateTSPIVersion(
  DWORD dwDeviceID,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwTSPIVersion
);

Parameters

dwDeviceID
Identifies the line device for which interface version negotiation is to be performed. In addition to device identifiers within the range the service provider supports, this may be the value:
INITIALIZE_NEGOTIATION
This value is used to signify that an overall interface version is to be negotiated.
dwLowVersion
The lowest TSPI version number under which TAPI can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
dwHighVersion
The highest TSPI version number under which TAPI can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
lpdwTSPIVersion
A pointer to a DWORD. The service provider fills this location with the highest TSPI version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns LINEERR_INCOMPATIBLEAPIVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

When dwDeviceID is INITIALIZE_NEGOTIATION, this function must not return LINEERR_OPERATIONUNAVAIL, because this function (with that value) is mandatory for negotiating the overall interface version even if the service provider supports no line devices.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

INITIALIZE_NEGOTIATION, TSPI Versioning, TSPI_lineGetExtensionID, TSPI_lineNegotiateExtVersion, TSPI_providerInit


TSPI_lineOpen

The TSPI_lineOpen function opens the line device whose device identifier is given, returning the service provider's handle for the device. The service provider must retain the TAPI handle for the device for use in subsequent calls to the LINEEVENT callback procedure.

LONG TSPIAPI TSPI_lineOpen(
  DWORD dwDeviceID,
  HTAPILINE htLine,
  LPHDRVLINE lphdLine,
  DWORD dwTSPIVersion,
  LINEEVENT lpfnEventProc
);

Parameters

dwDeviceID
Identifies the line device to be opened.
htLine
The TAPI handle for the line device to be used in subsequent calls to the LINEEVENT callback procedure to identify the device.
lphdLine
A pointer to an HDRVLINE where the service provider fills in its handle for the line device.
dwTSPIVersion
The TSPI version.
lpfnEventProc
A pointer to the LINEEVENT callback procedure supplied by TAPI that the service provider calls to report subsequent events on the line.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_ALLOCATED, LINEERR_OPERATIONUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider should reserve any non-sharable resources that are required to manage the line. However, any actions that can be postponed to lineMakeCall should be. It is a design assumption in TAPI that lineOpen is an "inexpensive" operation. For example, if the line is opened in monitor mode only, it should not be necessary for a COMM-port-based service provider to open the COMM port.

This procedure does not correspond directly to any procedure at the TAPI level, at which the functions of enabling device-specific extensions, selecting line characteristics, and setting media type detection are included in the functionality defined by lineOpen. At the TSPI level, these additional capabilities are separated out into TSPI_lineNegotiateExtVersion, TSPI_lineSetDefaultMediaDetection and TSPI_lineConditionalMediaDetection.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_CLOSE, LINEEVENT, TSPI_lineClose, TSPI_lineConditionalMediaDetection, TSPI_lineNegotiateExtVersion, TSPI_lineNegotiateTSPIVersion, TSPI_lineSetDefaultMediaDetection


TSPI_linePark

The TSPI_linePark function parks the specified call according to the specified park mode.

LONG TSPIAPI TSPI_linePark(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  DWORD dwParkMode,
  LPCWSTR lpszDirAddress,
  LPVARSTRING lpNonDirAddress
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be parked. The call state of hdCall can be connected.
dwParkMode
The park mode with which the call is to be parked, only one of the LINEPARKMODE_ constants.
lpszDirAddress
A pointer to null-terminated Unicode string that indicates the address where the call is to be parked when using directed park. The address is in dialable address format. This parameter is ignored for nondirected park.
lpNonDirAddress
A pointer to a structure of type VARSTRING. For nondirected park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park. Within the VARSTRING structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII string buffer containing a null-terminated string), and the terminating NULL is accounted for in the dwStringSize. If the memory pointed to by the lpNonDirAddress parameter is not large enough for the requested address, the TSPI_linePark function returns LINEERR_STRUCTURETOOSMALL.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALPARKMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL.

Remarks

All members of the VARSTRING structure, except dwTotalSize, are filled in by the service provider. The dwTotalSize member is filled in by TAPI, and the service provider must not overwrite this value.

Under directed park, the client application (through TAPI) specifies the address at which it wants to park the call. Under nondirected park, the switch determines the address and provides this to TAPI. In either case, a parked call can be unparked by specifying this address.

The parked call typically enters the idle call state after it is successfully parked. The service provider reports the new state using a LINE_CALLSTATE message. A subsequent TSPI_lineUnpark creates a new, distinct call handle, regardless of whether TSPI_lineCloseCall has destroyed the old handle.

Some switches can remind the user after a call has been parked for some long amount of time. The service provider reports this to TAPI as an offering call with a call reason set to reminder (if this is known).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEPARKMODE_ Constants, TSPI_lineCloseCall, TSPI_lineUnpark, VARSTRING


TSPI_linePickup

The TSPI_linePickup function picks up a call alerting at the specified destination address and returns a call handle for the picked-up call. If invoked with NULL for the lpszDestAddress parameter, a group pickup is performed. If required by the device capabilities, lpszGroupID specifies the group identifier to which the alerting station belongs.

LONG TSPIAPI TSPI_linePickup(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HTAPICALL htCall,
  LPHDRVCALL lphdCall,
  LPCWSTR lpszDestAddress,
  LPCWSTR lpszGroupID
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which a call is to be picked up.
dwAddressID
The address on hdLine at which the pickup is to be originated. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
htCall
The TAPI handle to the new call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.
lphdCall
A pointer to an HDRVCALL representing the service provider's identifier for the call. The service provider must fill this location with its handle for the call before this procedure returns. This handle is ignored by TAPI if the function results in an error.
lpszDestAddress
A pointer to a null-terminated Unicode string that contains the address whose call is to be picked up. The address is standard link format.
lpszGroupID
A pointer to a null-terminated Unicode string containing the group identifier to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

Note lpszGroupID can be specified by itself with a NULL pointer for lpszDestAddress. Alternatively, lpszGroupID can be specified in addition to lpszDestAddress, if required by the device. It can also be NULL itself.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALGROUPID, LINEERR_RESOURCEUNAVAIL.

Remarks

When a call has been picked up successfully, the service provider notifies TAPI with the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It lists the reason for the call as pickup. This structure is available by calling TSPI_lineGetCallInfo.

The service provider sets LINEADDRCAPFLAGS_PICKUPCALLWAIT to TRUE in the LINEADDRESSCAPS structure if TSPI_linePickup can be used to pick up a call for which the user has audibly detected the call-waiting signal, but for which the provider is unable to perform the detection. This gives the user a mechanism to answer a waiting call even though the service provider was unable to detect the call-waiting signal. When TSPI_linePickup is being used to pick up a call-waiting call, both lpszDestAddress and lpszGroupID pointer parameters are NULL. The service provider creates a new call handle for the waiting call and passes that handle to the user in lphdCall. The dwAddressID parameter is most often zero (particularly in single-line residential cases).

Once TSPI_linePickup is used to pick up the second call, TSPI_lineSwapHold can be used to toggle between them. TSPI_lineDrop can be used to drop one (and toggle to the other), and so forth. If the user wants to drop the current call and pick up the second call, they call TSPI_lineDrop when they get the call-waiting beep, wait for the second call to ring, and then call TSPI_lineAnswer on the new call handle. The service provider sets the LINEADDRFEATURE_PICKUP flag in the dwAddressFeatures member in LINEADDRESSSTATUS to indicate when pickup is actually possible.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEADDRESSCAPS, LINEADDRESSSTATUS, LINECALLINFO, LINECALLSTATUS, LINEEVENT, TSPI_lineAnswer, TSPI_lineDrop, TSPI_lineGetCallInfo, TSPI_lineGetCallStatus, TSPI_lineSwapHold


TSPI_linePrepareAddToConference

The TSPI_linePrepareAddToConference function prepares an existing conference call for the addition of another party. It creates a new, temporary consultation call. The new consultation call can be subsequently added to the conference call.

LONG TSPIAPI TSPI_linePrepareAddToConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdConfCall,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdConfCall
The handle to a conference call. The call state of hdConfCall can be connected.
htConsultCall
The TAPI handle to the new, temporary consultation call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new call. The call state of hdAddCall is not applicable.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for the new, temporary consultation call. The service provider must fill this location with its handle for the new call before this procedure returns. This handle is invalid if the function results in an error.
lpCallParams
A pointer to a LINECALLPARAMS containing call parameters to use when establishing the consultation call. This parameter is set to NULL if no special call setup parameters are desired.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_CONFERENCEFULL, LINEERR_INVALRATE, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCONFCALLHANDLE, LINEERR_USERUSERINFOTOOBIG.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the line is currently not in a state in which this operation can be performed. The service provider must indicate a list of currently valid operations in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure.

The service provider returns LINEERR_INVALCALLSTATE if the conference call is not in a valid state for the requested operation.

This function places an existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call with TSPI_lineAddToConference.

The consultation call can be canceled using TSPI_lineDrop. It may also be possible for TAPI to swap between the consultation call and the held conference call with TSPI_lineSwapHold. The service provider initially does media monitoring on the new call for at least the set of media types that were monitored for on the line.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEDEVSTATUS, LINEEVENT, TSPI_lineAddToConference, TSPI_lineDial, TSPI_lineDrop, TSPI_lineRemoveFromConference, TSPI_lineSetupConference, TSPI_lineSwapHold, LINECALLPARAMS


TSPI_lineReceiveMSPData

The TSPI_lineReceiveMSPData function service provider receives data sent by the media service provider (MSP). This function requires TAPI 3.0 version negotiation.

LONG TSPIAPI TSPI_lineReceiveMSPData(
    HDRVLINE hdLine,
    HDRVCALL hdCall,
    HDRVMSPLINE hdMSPLine,
    LPVOID pBuffer,
    DWORD dwSize
);

Parameters

hdLine
Handle to line device.
hdCall
Handle for call.
hdMSPLine
MSP handle for the call.
pBuffer
Pointer to buffer containing MSP data.
dwSize
Size of MSP data buffer.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

About The Media Service Provider (MSP), TSPI_lineMSPIdentify, TSPI_lineCreateMSPInstance, TSPI_lineCloseMSPInstance


TSPI_lineRedirect

The TSPI_lineRedirect function redirects the specified offering call to the specified destination address.

LONG TSPIAPI TSPI_lineRedirect(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be redirected. The call state of hdCall can be offering.
lpszDestAddress
Pointer to a null-terminated Unicode string that specifies the destination address. This follows the standard link format.
dwCountryCode
The country code of the party the call is redirected to. If a value of 0 is specified, a default is used by the implementation. This parameter is not validated by TAPI when this function is called.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCOUNTRYCODE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider does not redirect the call if it returns LINEERR_INVALADDRESS.

When this function is invoked, the service provider deflects the offering call to another address without first answering the call. Call redirect differs from call forwarding in that call forwarding is performed by the switch without the involvement of the called station; redirection can be done on a call-by-call basis by a client application, for example driven by caller ID information. It differs from call transfer in that transferring a call requires that the call first be answered.

After a call is successfully redirected, the call typically transitions to idle. The service provider indicates the new state using a LINE_CALLSTATE message.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineAccept, TSPI_lineDrop, TSPI_lineGetDevCaps


TSPI_lineReleaseUserUserInfo

The TSPI_lineReleaseUserUserInfo function informs the service provider that the user-user information contained in the LINECALLINFO structure has been processed, and that subsequently received user-user information can now be written into that structure. The service provider sends a LINE_CALLINFO message indicating LINECALLINFOSTATE_USERUSERINFO when new information is available.

LONG TSPIAPI TSPI_lineReleaseUserUserInfo(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call for which user-user information is to be released. The call state of hdCall can be any.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The TSPI_lineReleaseUserUserInfo function permits control of the flow of incoming user-user information on an ISDN connection. When a new, complete user-user information message is received, the service provider informs TAPI using a LINE_CALLINFO message (specifying LINECALLINFOSTATE_USERUSERINFO). The user-user information and other fields in LINECALLINFO can be examined by multiple calls to TSPI_lineGetCallInfo. The service provider must not overwrite previous user-user information in LINECALLINFO with newer information until after TSPI_lineReleaseUserUserInfo has been called. The service provider must buffer subsequently received user-user information until the previous information is released. Any remaining buffered information can be discarded when TSPI_lineCloseCall is invoked.

If this function is invoked while there is no user-user information in LINECALLINFO, the service provider should nevertheless return an indication of success.

For backward compatibility, TAPI automatically returns LINEERR_OPERATIONUNAVAIL if this function is invoked for a call on a line under the control of a service provider that does not export the function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.4 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLINFO, LINECALLINFO, TSPI_lineGetCallInfo


TSPI_lineRemoveFromConference

The TSPI_lineRemoveFromConference function removes the specified call from the conference call to which it currently belongs. The remaining calls in the conference call are unaffected.

LONG TSPIAPI TSPI_lineRemoveFromConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be removed from the conference. The call state of hdCall can be conferenced.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

This operation removes a party that currently belongs to a conference call. After the call has been successfully removed, it may be possible to further manipulate it using its handle. The availability of this operation and its result are likely to be limited in many implementations. For example, in many implementations, only the most recently added party can be removed from a conference, and the removed call may be automatically dropped (becomes idle). The service provider indicates its capabilities in LINEDEVCAPS with regard to the available effects of removing a call from a conference.

If the removal of a participant from a conference is supported, the service provider must indicate in the dwRemoveFromConfState member in LINEADDRESSCAPS the call state to which the call transitions after it is removed from the conference.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineAddToConference, TSPI_lineGetDevCaps, TSPI_lineSetupConference


TSPI_lineSecureCall

The TSPI_lineSecureCall function secures the call from any interruptions or interference that can affect the call's media stream.

LONG TSPIAPI TSPI_lineSecureCall(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be secured. The call state of hdCall can be any state except idle.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

A call can be secured to avoid interference. For example, in an analog environment, call waiting tones can destroy a fax or modem session on the original call. TSPI_lineSecureCall allows an existing call to be secured, TSPI_lineMakeCall provides the option to secure the call from the time of call setup. The securing of a call remains in effect for the duration of the call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, TSPI_lineMakeCall


TSPI_lineSelectExtVersion

The TSPI_lineSelectExtVersion function selects the indicated extension version for the indicated line device. Subsequent requests operate according to that extension version.

LONG TSPIAPI TSPI_lineSelectExtVersion(
  HDRVLINE hdLine,
  DWORD dwExtVersion
);

Parameters

hdLine
The handle to the line for which an extension version is to be selected.
dwExtVersion
The extension version to be selected. This version number has been negotiated using TSPI_lineNegotiateExtVersion. The most significant WORD is the major version number and the least significant WORD is the minor version number. Calling this function with a dwExtVersion of zero cancels the current selection.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The service provider selects the indicated extension version. Although the indicated version number may have been successfully negotiated, a different extension version may have been selected in the interim, in which case this function fails (returning LINEERR_INCOMPATIBLEEXTVERSION).

Subsequent operations on the line after an extension version has been selected behave according to that extension version. Subsequent attempts to negotiate the extension version report strictly the selected version or 0 (if the requested range does not include the selected version). Calling this procedure with the special extension version 0 cancels the current selection. The device becomes once again capable of supporting its full range of extension version numbers.

This function has no direct correspondence at the TAPI level, where selecting an extension version is bundled with the other functionality of lineOpen. The TSPI_lineSelectExtVersion function is typically called in two situations: (1) An application requested to open a line, the resulting change of media type monitoring was successful, the application requested that a particular extension version be used, and no extension version was currently selected. (2) The last application using a particular extension version closed the line, and the extension version selection can be canceled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineNegotiateExtVersion


TSPI_lineSendUserUserInfo

The TSPI_lineSendUserUserInfo function sends user-user information to the remote party on the specified call.

LONG TSPIAPI TSPI_lineSendUserUserInfo(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call on which to send user-user information. The call state of hdCall can be connected, offering, accepted, or ringback.
lpsUserUserInfo
A pointer to a null-terminated Unicode string containing user-user information to be sent to the remote party. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).
dwSize
The size, in bytes, of the user-user information in lpsUserUserInfo.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_OPERATIONUNAVAIL.

Remarks

This function can be used to send user-user information at any time during a connected call. If the size of the specified information to be sent is larger than what can fit into a single network message (as in ISDN), the service provider is responsible for breaking the information up into a sequence of chained network messages (using "more data").

User-user information can also be sent as part of call accept, call reject, call redirect, and when making calls. User-user information can also be received. The received information is reported in the call's LINECALLINFO structure. Whenever user-user information arrives after call offering or prior to call disconnect, a LINE_CALLINFO message with a UserUserInfo parameter notifies TAPI that user-user information in the call-information record has changed. If multiple network messages are chained, the information is assembled by the service provider and a single message is sent to TAPI.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_CALLINFO, LINECALLINFO, TSPI_lineAccept, TSPI_lineDrop, TSPI_lineGetCallInfo, TSPI_lineMakeCall, TSPI_lineRedirect


TSPI_lineSetAppSpecific

The TSPI_lineSetAppSpecific function sets the application-specific field of the specified call's LINECALLINFO structure.

LONG TSPIAPI TSPI_lineSetAppSpecific(
  HDRVCALL hdCall,
  DWORD dwAppSpecific
);

Parameters

hdCall
The handle to the call whose application-specific field is to be set. The call state of hdCall can be any state.
dwAppSpecific
The new content of the dwAppSpecific member for the call's LINECALLINFO structure. This value is uninterpreted by the service provider. This parameter is not validated by TAPI when this function is called.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The application-specific field in the LINECALLINFO data structure that exists for each call is uninterpreted by the Telephony API or any of its service providers. Its usage is entirely defined by the applications. The field can be read from the LINECALLINFO record returned by TSPI_lineGetCallInfo. However, TSPI_lineSetAppSpecific must be used to set the field so that changes become visible to other applications. When this field is changed, the service provider sends a LINE_CALLINFO message with an indication that the AppSpecific field has changed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_CALLINFO, LINECALLINFO, TSPI_lineGetCallInfo


TSPI_lineSetCallData

The TSPI_lineSetCallData function service provider stores the indicated call data with its information related to the call, and subsequently delivers it whenever TSPI_lineGetCallInfo is called. The service provider sends a LINE_CALLINFO message indicating LINECALLINFOSTATE_CALLDATA to show that the call data has changed. Depending on the service provider implementation, the call data can be propagated to all entities having handles to the call, including those on other machines (through the server), and can travel with the call when it is transferred.

LONG TSPIAPI TSPI_lineSetCallData(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPVOID lpCallData,
  DWORD dwSize
);

Parameters

dwRequestID
Identifier for reporting asynchronous completion information.
hdCall
The service provider's handle to the call.
lpCallData
Address of the data to be copied to the CallData field in LINECALLINFO, replacing any existing data.
dwSize
Number of bytes of data to be copied. A value of 0 causes any existing data to be removed.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CALLINFO, LINECALLINFO, TSPI_lineGetCallInfo


TSPI_lineSetCallHubTracking

The TSPI_lineSetCallHubTracking function sets the CallHub tracking mode. This function requires TAPI 3.0 version negotiation.

LONG TSPIAPI TSPI_lineSetCallHubTracking(
  HDRVLINE hdLine,
  LPLINECALLHUBTRACKINGINFO lpTrackingInfo
);

Parameters

hdLine
The service provider's handle to the call whose call information is to be retrieved. The call state of hdCall can be any state.
lpTrackingInfo
A pointer to a variably sized structure of type LINECALLHUBTRACKINGINFO. Upon successful completion of the request, this structure is filled with call-related information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE
LINEERR_NOMEM
LINEERR_OPERATIONFAILED
LINEERR_OPERATIONUNAVAIL
LINEERR_RESOURCEUNAVAIL

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

CallHub Object, LINECALLHUBTRACKINGINFO


TSPI_lineSetCallParams

The TSPI_lineSetCallParams function sets certain parameters for an existing call.

LONG TSPIAPI TSPI_lineSetCallParams(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  DWORD dwBearerMode,
  DWORD dwMinRate,
  DWORD dwMaxRate,
  LPLINEDIALPARAMS const lpDialParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call whose parameters are to be changed. The call state can be any state except idle and disconnected.
dwBearerMode
The new bearer mode for the call. The dwBearerMode parameter can have only one of the LINEBEARERMODE_ constants.
dwMinRate
A lower bound for the call's new data rate. TAPI can accept a new rate as low as this one. TAPI does not validate this parameter when this function is called.
dwMaxRate
An upper bound for the call's new data rate. This is the maximum data rate TAPI would like. Equal values for dwMinRate and dwMaxRate indicate that an exact data rate is required. TAPI does not validate this parameter when this function is called.
lpDialParams
A pointer to the new dial parameters for the call, of type LINEDIALPARAMS. If this parameter is NULL, it indicates that the call's current dialing parameters are to be used.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALRATE, LINEERR_RESOURCEUNAVAIL, LINEERR_BEARERMODEUNAVAIL.

Remarks

This operation is used to change the parameters of an existing call. Examples of its usage include changing the bearer mode and/or the data rate of an existing call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINECALLPARAMS, LINEDIALPARAMS, TSPI_lineMakeCall


TSPI_lineSetCallQualityOfService

The TSPI_lineSetCallQualityOfService function service provider attempts to renegotiate the QOS on the call with the switch If the desired QOS is not available, then the function fails, but the call continues with the previous QOS. If the function succeeds, the new QOS information is stored in LINECALLINFO; a LINECALLINFOSTATE_QOS message is sent by the service provider to indicate the updated values.

LONG TSPIAPI TSPI_lineSetCallQualityOfService(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPVOID lpSendingFlowspec,
  DWORD dwSendingFlowspecSize,
  LPVOID lpReceivingFlowspec,
  DWORD dwReceivingFlowspecSize
);

Parameters

dwRequestID
Identifier for reporting asynchronous function results.
hdCall
The service provider's handle to the call.
lpSendingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwSendingFlowspecSize
The total size in bytes of the FLOWSPEC and accompanying provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure.
lpReceivingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwReceivingFlowspecSize
The total size in bytes of the FLOWSPEC and accompanying provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLSTATE, LINEERR_INVALRATE, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINECALLINFO


TSPI_lineSetCallTreatment

The TSPI_lineSetCallTreatment function service provider stores the indicated dwCallTreatment in LINECALLINFO, and sends a LINE_CALLINFO message to indicate the updated information. If the call is currently in a state where the call treatment is relevant, the new treatment goes into effect at once; otherwise, it goes into effect the next time the call enters a relevant state.

LONG TSPIAPI TSPI_lineSetCallTreatment(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  DWORD dwTreatment
);

Parameters

dwRequestID
Identifier for reporting asynchronous function results.
hdCall
The service provider's handle to the call.
dwTreatment
One of the call treatment identifiers supported on the address on which the call appears.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CALLINFO, LINECALLINFO


TSPI_lineSetCurrentLocation

This TSPI_lineSetCurrentLocation function is obsolete. TAPI called this function when the user (using the Dialing Properties dialog box) or an application (using the lineSetCurrentLocation function) changed the address translation location.

Currently, a change in translation location results in a LINE_DEVSTATE message with dwParam1 set to LINEDEVSTATE_TRANSLATECHANGE.


TSPI_lineSetDefaultMediaDetection

The TSPI_lineSetDefaultMediaDetection procedure tells the service provider the new set of media types to detect for the indicated line (replacing any previous set). It also sets the initial set of media types that should be monitored for on subsequent calls (inbound or outbound) on this line.

LONG TSPIAPI TSPI_lineSetDefaultMediaDetection(
  HDRVLINE hdLine,
  DWORD dwMediaModes
);

Parameters

hdLine
The handle to the line to have media monitoring set.
dwMediaModes
The media type(s) of interest to TAPI. This parameter uses one of the LINEMEDIAMODE_ constants:

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL.

Remarks

TAPI typically calls this function to update the set of detected media types for the line to the union of all modes selected by all outstanding lineOpens whenever a line is Opened or Closed at the TAPI level. A lineOpen call attempt is rejected if media detection is rejected. A single call to this procedure is typically the result of a lineOpen call that does not specify the device identifier LINEMAPPER. The device identifier LINEMAPPER is never used at the TSPI level.

TAPI must compute the union of media types desired by all clients and pass the result to this function. The service provider uses the set passed to this function by TAPI. TAPI ensures that the dwMediaModes parameter has at least one bit set and that no reserved bits are set. The service provider must perform any further validity checks on the media types, such as checking whether any media types are indeed supported by the service provider. The union of all media types can be the value 0 if the applications that have the line open are all either monitors or not interested in handling incoming calls.

There is no directly corresponding function at the TAPI level. This procedure corresponds to the "request media types" implied for the specific line by the lineOpen procedure when it is called with the specific device identifier (other than LINEMAPPER).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINECALLPARAMS, LINEMEDIAMODE_ Constants, TSPI_lineClose


TSPI_lineSetDevConfig

The TSPI_lineSetDevConfig function restores the configuration of a device associated one-to-one with the line device from an "" data structure previously obtained using TSPI_lineGetDevConfig. The contents of this data structure are specific to the line [service provider] and device class.

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD dwSize,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to the configuration data structure that is returned in the variable portion of the VARSTRING structure by TSPI_lineGetDevConfig.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfig. This value is returned in the dwStringSize member in the VARSTRING structure returned by TSPI_lineGetDevConfig.
lpszDeviceClass
A pointer to a null-terminated Unicode string that specifies the device class of the device whose configuration is to be restored. Valid device class strings are the same as those specified for the TSPI_lineGetID function when it is applied to a "line" device (that is, when dwSelect has the value LINECALLSELECT_LINE).

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER.

Remarks

The call state is device specific.

The service provider returns LINEERR_INVALPARAM if the information contained in the structure pointed to by lpDeviceConfig is not valid for this device.

The service provider returns LINEERR_INVALLINESTATE if the device configuration cannot be changed in the current line state. The line may be in use by another application.

This function can be used to restore the configuration of a device associated one-to-one with the line device from a data structure previously retrieved from the service provider using the TSPI_lineGetDevConfig function. The lpszDeviceClass parameter selects which of among possibly several different classes of devices is to have its configuration restored. The set of supported classes is restricted to those whose devices correspond one-to-one with the line device. For more information about common device classes, see TSPI Device Classes.

A service provider typically allows the tapi/line device class under this function. It restores parameters that have "line" scope, such as the list of addresses in this line and the list of physical hardware devices such as COMM ports corresponding to the addresses or the maximum number of concurrent calls (if configurable).

In general, this function does NOT allow media-related device classes such as mci waveaudio, low level wave, or datamodem device classes, because these usually apply to a particular call or a particular address. Because there can be more than one of these per line device, the identification of the particular call or address simply by the line device identifier parameter in this function is ambiguous. An exception can be made for call-specific or address-specific device classes in cases where there is class configuration information that applies to the entire line device scope, such as initial defaults.

There are several reasons why exceptional support for call-specific and address-specific device classes is of only limited value under this function. First, because these classes can be ambiguous on multiple-address, multiple-call service providers, only a subset of service providers support them. Application programs are not likely to add a device-specific dependency on the inclusion of these classes in this function. Second, as higher-level media classes emerge that implement high-level protocols such as dial-in file system access in terms of low-level transport APIs, configuration for these classes tends toward instance scope instead of class scope. The high-level media API has to supply its own functions to configure call-specific or address-specific instances.

Whatever sort of devices and device classes this function supports, it can potentially affect two kinds of configuration information: permanent and temporary. Permanent information survives across different "opens" of the line, and even across different "inits" of the service provider itself. Temporary information survives only within a unique "open" of the line. When the line is closed, any such temporary information that has been set or retrieved through TSPI_lineGetDevConfig can revert to default or undefined values. The caller can reliably retrieve any temporary configuration only by a sequence such as TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. The caller can reliably set temporary configuration information retrieved by such a sequence through a sequence such as TSPI_lineOpen, TSPI_lineSetDevConfig. The temporary part of configuration remains stable only until the next TSPI_lineConfigDialog, TSPI_lineSetDevConfig, or TSPI_lineClose. The service provider must take care of storing any permanent part of the configuration, typically in an .ini file, and reloading it whenever the service provider is initialized.

The exact format of the data contained within the structure passed to this function is specific to the line and device class API, is undocumented, and is undefined. The structure passed to this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used from a previous TSPI_lineGetDevConfig to obtain the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this may work in some instances, it is not guaranteed). A service provider should check this data structure for consistency to guard against failures due to a client application passing incompatible information.

Note Some service providers may permit the configuration to be set while a device is in use, and others may not.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineClose, TSPI_lineConfigDialog, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineOpen, VARSTRING


TSPI_lineSetLineDevStatus

The TSPI_lineSetLineDevStatus service provider sets the device status as indicated, sending appropriate LINE_LINEDEVSTATE messages to indicate the new status.

LONG TSPIAPI TSPI_lineSetLineDevStatus(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwStatusToChange,
  DWORD fStatus
);

Parameters

dwRequestID
Identifier for reporting asynchronous function results.
hdLine
The service provider's handle to the line device.
dwStatusToChange
One or more of the LINEDEVSTATUSFLAGS_ constants.
fStatus
TRUE to turn on the indicated status bit(s), FALSE to turn off.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALLINESTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_LINEDEVSTATE


TSPI_lineSetMediaControl

The TSPI_lineSetMediaControl function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media types, custom tones, and call states. The new specified media controls replace all the ones that were in effect for this line, address, or call prior to this request.

LONG TSPIAPI TSPI_lineSetMediaControl(
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  DWORD dwSelect,
  LPLINEMEDIACONTROLDIGIT const lpDigitList,
  DWORD dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const lpMediaList,
  DWORD dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const lpToneList,
  DWORD dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD dwCallStateNumEntries
);

Parameters

hdLine
The handle to a line.
dwAddressID
An address on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. TAPI does not validate this parameter when this function is called.
hdCall
The handle to a call. The call state of hdCall can be any state.
dwSelect
Specifies whether media control is requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This parameter uses the following LINECALLSELECT_ constants.
lpDigitList
A pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit listed in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

dwDigitNumEntries
The number of entries in the lpDigitList. TAPI does not validate this parameter when this function is called.
lpMediaList
A pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media type to be monitored, media-type specific information (such as duration), and a media control field. If a media type in the list is detected, the corresponding media control action is performed on the call's media stream.
dwMediaNumEntries
The number of entries in lpMediaList. TAPI does not validate this parameter when this function is called.
lpToneList
A pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media control field. If a tone in the list is detected, the corresponding media control action is performed on the call's media stream.
dwToneNumEntries
The number of entries in lpToneList. TAPI does not validate this parameter when this function is called.
lpCallStateList
A pointer to an array with entries of type LINEMEDIACONTROLCALLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action.
dwCallStateNumEntries
The number of entries in lpCallStateList. TAPI does not validate this parameter when this function is called.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALADDRESSID, LINEERR_INVALPOINTER, LINEERR_INVALCALLHANDLE, LINEERR_INVALTONELIST, LINEERR_INVALCALLSELECT, LINEERR_NOMEM, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITLIST, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIALIST.

Remarks

This function returns zero (success) when media control is correctly initiated, not when any media control takes effect. Media control in progress is changed or is canceled when this function is called again with either different parameters or NULLs.

Only a single media control request can be outstanding on a call at one time. A request replaces any that may be outstanding.

Depending on the service provider and other activities that compete for such resources, the amount of simultaneous detections that can be made can vary over time. If service provider resources are overcommitted, it returns LINEERR_RESOURCEUNAVAIL.

Whether or not media control is supported by the service provider is a device capability indicated in LINEDEVCAPS.

Each time TSPI_lineSetMediaControl is called, the new request overrides any media control currently in effect. If one or more of the parameters lpDigitList, lpMediaList, lpToneList, and lpCallStateList are NULL, the corresponding digit, media type, tone, or call state-triggered media control is disabled. To modify just a portion of the media control parameters while leaving the remaining settings in effect, the application should invoke TSPI_lineSetMediaControl supplying the previous parameters for those potions that must remain in effect, and new parameters for those parts that are to be modified.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINEDEVCAPS, LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE, LINEDIGITMODE_ Constants, LINEMEDIAMODE_ Constants, TSPI_lineGetDevCaps


TSPI_lineSetMediaMode

The TSPI_lineSetMediaMode function changes the call's media as stored in the call's LINECALLINFO structure.

LONG TSPIAPI TSPI_lineSetMediaMode(
  HDRVCALL hdCall,
  DWORD dwMediaMode
);

Parameters

hdCall
The handle to the call undergoing a change in media type. The call state of hdCall can be any state.
dwMediaMode
The new media type(s) for the call. As long as the LINEMEDIAMODE_UNKNOWN media type flag is set, multiple other media type flags can be set as well. This is used to identify a call's media type as not fully determined, but narrowed down to one of just a small set of specified media types. If the LINEMEDIAMODE_UNKNOWN flag is not set, only a single media type can be specified. This parameter uses one (or more) of the LINEMEDIAMODE_ constants.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

Other than changing the call's media as stored in the call's LINECALLINFO structure, this procedure is simply advisory in the sense that it indicates an expected media change that is about to occur, rather than forcing a specific change to the call. Typical usage is to set a call's media type to a specific known media type, or to exclude possible media types as long as the call's media type is not fully known (the UNKNOWN media type flag is set).

TAPI makes the following guarantees regarding the passed media type: (1) there is at least one bit set, (2) there are no reserved bits set, and (3) if more than one bit is set, "Unknown" is also set. The service provider must perform any further validity checks on the media types, such as checking whether any media types are indeed supported by the service provider.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINECALLINFO, LINEMEDIAMODE_ Constants, TSPI_lineGetCallInfo


TSPI_lineSetStatusMessages

The TSPI_lineSetStatusMessages function enables TAPI to specify which notification messages the service provider should generate for events related to status changes for the specified line or any of its addresses.

LONG TSPIAPI TSPI_lineSetStatusMessages(
  HDRVLINE hdLine,
  DWORD dwLineStates,
  DWORD dwAddressStates
);

Parameters

hdLine
The handle to the line device for which the new filter is to be set.
dwLineStates
A bit array that identifies for which line device status changes a message is to be sent to TAPI. This parameter uses one of the LINEDEVSTATE_ constants.
dwAddressStates
A bit array that identifies for which address status changes a message is to be sent to TAPI. This parameter uses one of the LINEADDRESSSTATE_ constants.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALADDRESSSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the dwLineStates parameter contains one or more bits that are not LINEDEVSTATE_ constants.

Win32 Telephony defines a number of messages that notify applications about events occurring on lines and addresses. The sets of all change messages in which all applications are interested can be much smaller than the set of possible messages. This procedure allows TAPI to tell the service provider the reduced set of messages to deliver. The service provider delivers all of the messages it supports, within the specified set. It is permitted to deliver more (they are filtered out by TAPI), but is discouraged from doing so for performance reasons. If TAPI requests delivery of a particular message type that is not produced by the provider, the provider nevertheless accepts the request but simply does not produce the message. By default, address and line status reporting is initially disabled for a line.

This function differs from the corresponding TAPI function as follows: (1) The set of messages requested is the union of all sets requested by applications at the TAPI level. (2) The message set is neither reduced nor augmented by ownership (because there is no concept of ownership at the TSPI level) (3) The set is advisory in the sense that the service provider is required to forward at least the indicated set of messages but is permitted to forward a larger set.

Device state changes regarding Open and Close are not reported, because at the TSPI level there is only one outstanding Open at a time.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_ADDRESSSTATE, LINE_CLOSE, LINE_LINEDEVSTATE, LINEADDRESSSTATE_ Constants, LINEDEVSTATE_ Constants


TSPI_lineSetTerminal

The TSPI_lineSetTerminal function enables TAPI to specify to which terminal information related to the specified line, address, or call is to be routed. This operation can be used while calls are in progress on the line, to allow events to be routed to different devices as required.

LONG TSPIAPI TSPI_lineSetTerminal(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  DWORD dwSelect,
  DWORD dwTerminalModes,
  DWORD dwTerminalID,
  DWORD bEnable
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to a line.
dwAddressID
An address on the given open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. TAPI does not validate this parameter when this function is called.
hdCall
The handle to a call. The call state can be any state (if dwSelect is LINECALLSELECT_CALL).
dwSelect
Specifies whether the terminal setting is requested for the line, the address, or just the specified call. If line or address is specified, events either apply to the line or address itself or serve as a default initial setting for all new calls on the line or address. This parameter uses one of the LINECALLSELECT_ constants.
dwTerminalModes
The class(es) of low level events to be routed to the given terminal. Use one of the LINETERMMODE_ Constants for this parameter.
dwTerminalID
The device identifier of the terminal device where the given events are to be routed. Terminal identifiers are small integers in the range from 0 through dwNumTerminals minus one, where dwNumTerminals and the terminal modes each terminal is capable of handling are indicated by the service provider in LINEDEVCAPS.

Note These terminal identifiers have no relation to other device identifiers and are defined by the service provider through device capabilities. TAPI does not validate this parameter when this function is called.

bEnable
If TRUE, dwTerminalID is valid and the specified event classes are routed to or from that terminal. If FALSE, these events are not routed to or from the dwTerminalID. TAPI does not validate this parameter when this function is called.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_INVALTERMINALID, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTERMINALMODE, LINEERR_OPERATIONFAILED.

Remarks

The service provider returns LINEERR_RESOURCEUNAVAIL if the operation cannot be completed because of resource overcommitment or if too many terminals are set, due either to hardware limitations or to service provider/device driver limitations.

TAPI can use this operation to route certain classes of low-level line events to the specified terminal device, or to suppress the routing of these events altogether. For example, voice can be routed to a separate audio I/O device (headset), lamps and display events can be routed to the local phone device, and button events and ringer events can be suppressed altogether.

Call progress tones and/or messages get routed to the same place as media. For example, if audio signals are going to the phone, then so are busy signals (analog) or Q.931 messages indicating busy (digital).

The service provider must determine whether the combinations of dwSelect and dwTerminalModes are legal.

This operation can be called any time, even when a call is active on the given line device. This, for example, allows a user to switch from using the local phone set to another audio I/O device.

This function can be called multiple times to route the same events to multiple terminals simultaneously. To reroute events to a different terminal, TAPI recommends that the application first disable routing to the existing terminal and next route the events to the new terminal. However, the service provider should make its best effort to accommodate the application's requests in any sequence.

Terminal identifier assignments are made by the service provider, and LINEDEVCAPS indicates which terminal identifiers the service provider has available. Service providers that don't support this type of event routing indicate that they have no terminal devices (dwNumTerminals in LINEDEVCAPS is set to zero).

LineSetTerminal on a line or address affects all existing calls on that line or address, but does not affect calls on other addresses. It also sets the default for future calls on that line or address. A line or address that has multiple connected calls active at any one time can have different routing in effect for each call.

Disabling the routing of low-level events to a terminal when these events are not currently routed to or from that terminal is not required to generate an error so long as after the function succeeds, the specified events are not routed to or from that terminal.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINECALLSELECT_ Constants, LINETERMMODE_ Constants


TSPI_lineSetupConference

The TSPI_lineSetupConference function sets up a conference call for the addition of the third party.

LONG TSPIAPI TSPI_lineSetupConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  HDRVLINE hdLine,
  HTAPICALL htConfCall,
  LPHDRVCALL lphdConfCall,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  DWORD dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the initial call that identifies the first party of a conference call. In some environments, a call must exist in order to start a conference call. In other telephony environments, no call initially exists and hdCall is left NULL. The call state of hdCall can be connected.
hdLine
The handle to the line device on which to originate the conference call if hdCall is NULL. The hdLine parameter is ignored if hdCall is non-NULL. The service provider reports which model it supports through the setupConfNull flag of the LINEADDRESSCAPS data structure.
htConfCall
The TAPI handle to the new conference call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new call.
lphdConfCall
A pointer to an HDRVCALL representing the service provider's identifier for the newly created conference call. The service provider must fill this location with its handle for the new call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConfCall is not applicable.
htConsultCall
The TAPI handle to the consultation call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The service provider must save the htConsultCall and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new consultation call.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for a call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The service provider must fill this location with its handle for the new consultation call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConsultCall is not applicable.
dwNumParties
The expected number of parties in the conference call. The service provider is free to do with this number as it pleases. For example, the service provider can ignore it, or use it as a hint to allocate the right size conference bridge inside the switch. TAPI does not validate this parameter when this function is called.
lpCallParams
A pointer to a LINECALLPARAMS structure containing call parameters to use when establishing the consultation call. This parameter is set to NULL if no special call setup parameters are desired and the service provider uses default parameters.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_INVALADDRESSMODE, LINEERR_INVALLINEHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALCALLPARAMS, LINEERR_CALLUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CONFERENCEFULL, LINEERR_INVALMEDIAMODE, LINEERR_NOMEM, LINEERR_INVALRATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_USERUSERINFOTOOBIG, LINEERR_BEARERMODEUNAVAIL.

Remarks

The service provider returns LINEERR_INVALLINEHANDLE if the specified line handle for the line containing the conference call is invalid. This error can also indicate that the telephony environment requires an initial line to set up a conference but a non-NULL call handle was supplied instead.

The service provider returns LINEERR_INVALCALLHANDLE if the telephony environment requires an initial call to set up a conference but a NULL call handle was supplied instead.

TSPI_lineSetupConference provides two ways to establish a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hdCall parameter is a valid call handle that is initially added to the conference call by the TSPI_lineSetupConference request and hdLine is ignored. On switches where conference call setup does not start with an existing call, hdCall must be NULL and hdLine must be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. TAPI can use TSPI_lineDial to dial the address of the other party.

The conference call typically transitions into the onHoldPendingConference state, the consultation call dialtone state and the initial call (if one) into the conferenced state.

A conference call can also be set up using a TSPI_lineCompleteTransfer function that is resolved into a three-way conference.

TAPI may be able to toggle between the consultation call and the conference call using TSPI_lineSwapHold.

The TSPI_lineUnhold function can recover calls that have the call state onHoldPendingConference. If this is done, any consultation call typically goes to the idle state.

A consultation call can be canceled by invoking TSPI_lineDrop on it. When dropping a consultation call, the existing conference call typically transitions back to the connected state. TAPI and its client applications should observe the LINE_CALLSTATE messages to determine exactly what happens to the calls. For example, if the conference call reverts back to a regular two-party call, the conference call becomes idle and the original participant call may revert to connected.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEADDRESSCAPS, LINEADDRCAPFLAGS_ Constants, LINEEVENT, TSPI_lineAddToConference, TSPI_lineDial, TSPI_linePrepareAddToConference, TSPI_lineRemoveFromConference, TSPI_lineSwapHold, LINECALLPARAMS


TSPI_lineSetupTransfer

The TSPI_lineSetupTransfer function initiates a transfer of the call specified by hdCall. It establishes a consultation call, lphdConsultCall, on which the party can be dialed that can become the destination of the transfer.

LONG TSPIAPI TSPI_lineSetupTransfer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be transferred. The call state of hdCall can be connected.
htConsultCall
The TAPI handle to the new, temporary consultation call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new consultation call.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for the new consultation call. The service provider must fill this location with its handle for the new consultation call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConsultCall is not applicable.

When setting a call up for transfer, another call (a consultation call) is automatically allocated to enable the application (through TAPI) to dial the address (using TSPI_lineDial) of the party to where the call is to be transferred. The originating party can carry on a conversation over this consultation call prior to completing the transfer.

This transfer procedure may not be valid for some line devices. Instead of calling this procedure, TAPI may need to unhold an existing held call (using TSPI_lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary to set up the consultation call as an entirely new call using TSPI_lineMakeCall, to the destination of the transfer.

The transferHeld and transferMake flags in the LINEADDRESSCAPS data structure report what model the service provider uses.

lpCallParams
A pointer to a LINECALLPARAMS structure containing call parameters to use when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired (the service provider uses defaults).

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_NOMEM, LINEERR_INVALLINESTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INUSE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_BEARERMODEUNAVAIL, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_USERUSERINFOTOOBIG.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the call to be transferred is not in a valid state.

This operation sets up the transfer of the call specified by hdCall. The setup phase of a transfer establishes a consultation call to send the address of the destination (the party to be transferred to) to the switch, while the call to be transferred is kept on hold. This new call is referred to as a consultation call (hdConsultCall) and can be manipulated (for example, dropped) independently of the original call.

When the consultation call has reached the dialtone call state, TAPI can continue transferring the call either by dialing the destination address and tracking its progress, or by unholding an existing call. The transfer of the original call to the selected destination is completed using TSPI_lineCompleteTransfer.

While the consultation call exists, the original call typically transitions to the onholdPendingTransfer state.

The TSPI_lineUnhold function can recover calls that have the call state onHoldPendingTransfer. If this is done, any consultation call typically goes to the idle state.

In telephony environments that follow the transferHeld or transferMake transfer models, this procedure returns LINEERR_OPERATIONFAILED and does not allocate a consultation call handle.

A consultation call can be canceled by invoking TSPI_lineDrop on it. After dropping a consultation call, the original call typically transitions back to the connected state.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

LINE_CALLSTATE, LINEADDRESSCAPS, TSPI_lineBlindTransfer, TSPI_lineCompleteTransfer, TSPI_lineDial, TSPI_lineDrop, TSPI_lineSwapHold, TSPI_lineUnhold, LINECALLPARAMS


TSPI_lineSwapHold

The TSPI_lineSwapHold function swaps the specified active call with the specified call on consultation hold.

LONG TSPIAPI TSPI_lineSwapHold(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdActiveCall,
  HDRVCALL hdHeldCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdActiveCall
The handle to the call to be swapped with the call on consultation hold. The call state of hdActiveCall can be connected.
hdHeldCall
The handle to the consultation call. The call state of hdHeldCall can be onHoldPendingTransfer, onHoldPendingConference, or onHold.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider must send LINE_CALLSTATE messages for the call transitions.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineSetupConference, TSPI_lineSetupTransfer


TSPI_lineUncompleteCall

The TSPI_lineUncompleteCall function is used to cancel the specified call competion request on the specified line.

LONG TSPIAPI TSPI_lineUncompleteCall(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwCompletionID
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which a call completion is to be canceled.
dwCompletionID
The completion identifier for the request that is to be canceled. TAPI does not validate this parameter when this function is called.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCOMPLETIONID, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, TSPI_lineCompleteCall


TSPI_lineUnhold

The TSPI_lineUnhold function retrieves the specified held call.

LONG TSPIAPI TSPI_lineUnhold(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be retrieved. The call state of hdCall can be onHold.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the call is not currently on hold.

This operation works for calls on hard hold (calls placed on hold using TSPI_lineHold) and on soft hold. The service provider should check that the call is currently in the onHold, onHoldPendingTransfer, or onHoldPendingConference state, change the state to connected, and send a LINECALLSTATE message for the new call state.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineHold


TSPI_lineUnpark

The TSPI_lineUnpark function retrieves the call parked at the specified address and returns a call handle for it.

LONG TSPIAPI TSPI_lineUnpark(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HTAPICALL htCall,
  LPHDRVCALL lphdCall,
  LPCWSTR lpszDestAddress
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which a call is to be unparked.
dwAddressID
The address on hdLine at which to originate the unpark. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. TAPI does not validate this parameter when this function is called.
htCall
The TAPI handle to the new unparked call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.
lphdCall
A pointer to an HDRVCALL representing the service provider's identifier for the new unparked call. The service provider must fill this location with its handle for the call before this procedure returns. This handle is invalid if the function results in an error.
lpszDestAddress
A pointer to a null-terminated Unicode string that contains the address where the call is parked. The address is in dialable address format.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL.

Remarks

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

The call handle created by this function is a new, distinct, call handle even if an original call handle for the call is still in existence (it has not been destroyed by TSPI_lineCloseCall).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, TSPI_lineCloseCall, TSPI_linePark


TSPI Phone Device Functions

This section contains an alphabetic list of the phone device functions in the Telephony SPI. The TSPI phone device functions include:

  • TSPI_phoneClose
  • TSPI_phoneConfigDialog
  • TSPI_phoneDevSpecific
  • TSPI_phoneGetButtonInfo
  • TSPI_phoneGetData
  • TSPI_phoneGetDevCaps
  • TSPI_phoneGetDisplay
  • TSPI_phoneGetExtensionID
  • TSPI_phoneGetGain
  • TSPI_phoneGetHookSwitch
  • TSPI_phoneGetIcon
  • TSPI_phoneGetID
  • TSPI_phoneGetLamp
  • TSPI_phoneGetRing
  • TSPI_phoneGetStatus
  • TSPI_phoneGetVolume
  • TSPI_phoneNegotiateExtVersion
  • TSPI_phoneNegotiateTSPIVersion
  • TSPI_phoneOpen
  • TSPI_phoneSelectExtVersion
  • TSPI_phoneSetButtonInfo
  • TSPI_phoneSetData
  • TSPI_phoneSetDisplay
  • TSPI_phoneSetGain
  • TSPI_phoneSetHookSwitch
  • TSPI_phoneSetLamp
  • TSPI_phoneSetRing
  • TSPI_phoneSetStatusMessages
  • TSPI_phoneSetVolume


TSPI_phoneClose

The TSPI_phoneClose function closes the specified open phone device after completing or aborting all outstanding asynchronous operations on the device.

long TSPIAPI TSPI_phoneClose(
  HDRVPHONE hdPhone
);

Parameters

hdPhone
The service provider's opaque handle to the phone to be closed. After the phone is successfully closed, this handle is no longer valid.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

The service provider must report completion for every asynchronous operation. If this procedure is called for a phone on which there are outstanding asynchronous operations, the operations should be reported complete with an appropriate result or error code before this procedure returns. Generally, TAPI waits for these to complete in an orderly fashion. However, the service provider should be prepared to handle an early call to TSPI_phoneClose in "abort" or "emergency shutdown" situtations.

After this procedure returns the service provider must report no further events on the phone. The service provider's opaque handle for the phone becomes invalid.

The service provider must relinquish nonsharable resources it reserves while the phone is open. For example, closing a phone accessed through a comm port and modem should result in closing the comm port, making it available for use by other applications.

This function should always succeed except in extraordinary circumstances. Most callers will probably ignore the return code because they will be unable to compensate for any error that occurs. The specified return values are more advisory for development diagnostic purposes than anything else.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONE_CLOSE


TSPI_phoneConfigDialog

The TSPI_phoneConfigDialog function is obsolete.TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_phoneConfigDialog.

The TSPI_phoneConfigDialog function causes the provider of the specified phone device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the phone device.

LONG TSPIAPI TSPI_phoneConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The phone device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box is selected.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INUSE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_RESOURCEUNAVAIL.

Remarks

TSPI_phoneConfigDialog causes the service provider to display a modal dialog box as a child window of hWndOwner to allow the user to configure parameters related to the phone specified by dwDeviceID. The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested. The permitted strings are the same as for TSPI_phoneGetID. For example, if the phone supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters). The szDeviceClass parameter should be "tapi/phone", "", or NULL to cause the provider to display the highest level configuration for the phone.

The procedure must update the [Windows Telephony] section in the Win.ini file and broadcast the WM_WININICHANGE message if it makes any changes to Telephon.ini that affect the contents of structures visible to applications (such as PHONECAPS), or if phone devices are created or removed.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 only.
Version: Requires TAPI 1.4 or earlier.
Header: Declared in Tspi.h.

See Also

PHONECAPS, TSPI_phoneGetID


TSPI_phoneDevSpecific

The TSPI_phoneDevSpecific function is used as a general extension mechanism to enable a Telephony API implementation to provide features not described in the other operations. The meanings of these extensions are device specific.

LONG TSPIAPI TSPI_phoneDevSpecific(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone on which a device-specific operation is to be performed.
lpParams
A pointer to a memory area used to hold a parameter block. Its interpretation is device specific. The lpParams parameter should not contain pointers. To get information back to the application from TSPI_phoneDevSpecific, the service provider sends a PHONE_DEVSPECIFIC message with the information.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_RESOURCEUNAVAIL.

Remarks

Additional return values are device specific.

This operation provides a generic parameter profile. The interpretation of the parameter block is device specific. Indications and replies that are device specific should use the PHONE_DEVSPECIFIC message.

This function is called in direct response to an application that has called the TAPI phoneDevSpecific function. TAPI translates the hPhone parameter used at the TAPI level to the corresponding hdPhone parameter used at the TSPI level. The lpParams buffer is passed through unmodified.

A service provider can provide access to device-specific functions by defining parameters for use with this operation. Applications that want to make use of these device-specific extensions should consult the device-specific (vendor-specific) documentation that describes what extentions are defined.

Note An application that relies on these device-specific extensions is typically not portable in working with other service provider environments.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONE_DEVSPECIFIC


TSPI_phoneGetButtonInfo

The TSPI_phoneGetButtonInfo function returns information about a specified button.

LONG TSPIAPI TSPI_phoneGetButtonInfo(
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO lpButtonInfo
);

Parameters

hdPhone
The handle to the phone to be queried.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to memory into which the service provider writes a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode and function, and provides additional descriptive text corresponding to the button. Prior to calling TSPI_phoneGetButtonInfo, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONLAMPID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NOMEM.

Remarks

The TSPI_phoneGetButtonInfo function returns the PHONEERR_NOMEM value if the service provider cannot access the memory containing the button information.

The service provider fills in all the members of the PHONEBUTTONINFO data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONEBUTTONINFO, PHONECAPS, TSPI_phoneSetButtonInfo


TSPI_phoneGetData

The TSPI_phoneGetData function uploads the information from the specified location in the open phone device to the specified buffer.

LONG TSPIAPI TSPI_phoneGetData(
  HDRVPHONE hdPhone,
  DWORD dwDataID,
  LPVOID lpData,
  DWORD dwSize
);

Parameters

hdPhone
The handle to the phone to be queried.
dwDataID
Specifies where in the phone device the buffer is to be uploaded from.
lpData
A pointer to the memory buffer where the data is to be uploaded to.
dwSize
The size of the data buffer in bytes.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDATAID, PHONEERR_RESOURCEUNAVAIL.

Remarks

The TSPI_phoneGetData function uploads a maximum of dwSize bytes from the phone device into lpData. If dwSize is zero, nothing is copied. The size of each data area is listed in the phone's PHONECAPS structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetData


TSPI_phoneGetDevCaps

The TSPI_phoneGetDevCaps function queries a specified phone device to determine its telephony capabilities.

LONG TSPIAPI TSPI_phoneGetDevCaps(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwExtVersion,
  LPPHONECAPS lpPhoneCaps
);

Parameters

dwDeviceID
The phone device to be queried.
dwTSPIVersion
The negotiated TSPI version number. This value is negotiated for this device through the TSPI_phoneNegotiateTSPIVersion function.
dwExtVersion
The negotiated extension version number. This value is negotiated for this device through the TSPI_phoneNegotiateExtVersion function.
lpPhoneCaps
A pointer to memory into which the service provider writes a variably sized structure of type PHONECAPS. Upon successful completion of the request, this structure is filled with phone device capability information. Prior to calling TSPI_phoneGetDevCaps, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_NODRIVER, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The service provider fills in all the members of the PHONEBUTTONINFO data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

If dwExtVersion is zero, no extension information is requested. If it is nonzero, it holds a value that has already been negotiated for this device with the TSPI_phoneNegotiateExtVersion function. The service provider fills in device- and vendor-specific extended information according to the extension version specified.

After the service provider returns from the TSPI_phoneGetDevCaps function, TAPI sets the dwPhoneStates member of the PHONECAPS structure as follows:

PHONECAPS.dwPhoneStates |=
    PHONESTATE_OWNER |
    PHONESTATE_MONITORS |
    PHONESTATE_REINIT;

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONEBUTTONINFO, PHONECAPS, TSPI_phoneNegotiateExtVersion


TSPI_phoneGetDisplay

The TSPI_phoneGetDisplay function returns the current contents of the specified phone display.

LONG TSPIAPI TSPI_phoneGetDisplay(
  HDRVPHONE hdPhone,
  LPVARSTRING lpDisplay
);

Parameters

hdPhone
The handle to the phone to be queried.
lpDisplay
A pointer to the memory location where the display content is to be stored by the provider, of type VARSTRING. Prior to calling TSPI_phoneGetDisplay, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

The lpDisplay memory area should be at least dwDisplayNumRows * dwDisplayNumColumns elements in size to receive all of the display information. The dwDisplayNumRows and dwDisplayNumColumns members are available in the PHONECAPS structure returned by TSPI_phoneGetDevCaps.

The service provider fills in all the members of the VARSTRING data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetDisplay, VARSTRING


TSPI_phoneGetExtensionID

The TSPI_phoneGetExtensionID function retrieves the extension identifier that the service provider supports for the indicated phone device.

LONG TSPIAPI TSPI_phoneGetExtensionID(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  LPPHONEEXTENSIONID lpExtensionID
);

Parameters

dwDeviceID
The phone device to be queried.
dwTSPIVersion
Specifies an interface version number that is negotiated for this device using TSPI_phoneNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
lpExtensionID
A pointer to a structure of type PHONEEXTENSIONID. If the service provider supports provider-specific extensions, it fills this structure with the extension identifier of these extensions. If the service provider does not support extensions, it fills this structure with all zeros. An extension identifier of all zeros is not a legal extension identifier, since the all-zeros value is used to indicate that the service provider does not support extensions.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

This function is typically called by TAPI in response to an application calling the phoneNegotiateAPIVersion function. The result returned by the service provider should be appropriate for use in a subsequent call to TSPI_phoneNegotiateExtVersion.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

PHONEEXTENSIONID, TSPI_phoneNegotiateExtVersion, TSPI_phoneNegotiateTSPIVersion


TSPI_phoneGetGain

The TSPI_phoneGetGain function returns the gain setting of the microphone of the specified phone's hookswitch device.

LONG TSPIAPI TSPI_phoneGetGain(
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwGain
);

Parameters

hdPhone
The handle to the phone whose gain is to be retrieved.
dwHookSwitchDev
The hookswitch device whose gain level is queried. This parameter may be one and only one of the PHONEHOOKSWITCHDEV_ Constants.
lpdwGain
A pointer to a DWORD-sized location into which the service provider writes the current gain setting of the hookswitch microphone component. The dwGain gain parameter specifies the volume level of the hookswitch device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service provider-specific.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetGain


TSPI_phoneGetHookSwitch

The TSPI_phoneGetHookSwitch function returns the current hookswitch mode of the specified open phone device.

LONG TSPIAPI TSPI_phoneGetHookSwitch(
  HDRVPHONE hdPhone,
  LPDWORD lpdwHookSwitchDevs
);

Parameters

hdPhone
The service provider's opaque handle to the phone whose hookswitch mode is to be retrieved.
lpdwHookSwitchDevs
A pointer to a DWORD-sized location into which the service provider writes the mode of the phone's hookswitch devices. This parameter uses one of the PHONEHOOKSWITCHDEV_ constants. If a bit position is FALSE, the corresponding hookswitch device is onhook. If TRUE, the microphone and/or speaker part of the corresponding hookswitch device is offhook. To find out whether microphone and/or speaker are enabled, TAPI can use TSPI_phoneGetStatus.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

After the hookswitch state of a device changes, and if hookswitch monitoring is enabled, TAPI is sent a PHONE_STATE message.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONE_STATE, PHONEHOOKSWITCHDEV_ Constants, PHONESTATUS, TSPI_phoneGetStatus, TSPI_phoneSetHookSwitch


TSPI_phoneGetIcon

The TSPI_phoneGetIcon function retrieves a service phone device-specific (or provider-specific) icon to display to the user.

LONG TSPIAPI TSPI_phoneGetIcon(
  DWORD dwDeviceID,
  LPCWSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The phone device whose icon is requested.
lpszDeviceClass
A pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific sub icon applicable to that device class. This parameter is optional and can be left NULL or be empty, in which case the highest level icon associated with the phone device rather than a specified media stream device is selected.
lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALDEVICECLASS, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

TSPI_phoneGetIcon causes the provider to return a handle (in the DWORD pointed to by lphIcon) to an icon resource (obtained from the Win32 LoadIcon function) associated with the specified phone. The icon handle is for a resource associated with the provider.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for TSPI_phoneGetID. For example, if the phone supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. For more information about common device classes, see TSPI Device Classes.

The parameters "tapi/phone", "", or NULL can be used to request the icon for the phone device. A provider can choose to support many icons (selected by lpszDeviceClass and/or phone number), a single icon (such as for the manufacturer, which would be returned for all phoneGetIcon requests regardless of the lpszDeviceClass selected), or no icons, in which case it sets the DWORD pointed to by lphIcon to NULL. TAPI examines the handle returned by the provider, and if the provider returns NULL, TAPI substitutes a generic Win32 Telephony icon included as a resource in TAPI (the generic phone icon).

If the service provider supports no icons, it can leave this function unimplemented, in which case TAPI provides a generic phone icon for the application.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

TSPI_phoneConfigDialog, TSPI_phoneGetID


TSPI_phoneGetID

The TSPI_phoneGetID function returns a device identifier for the given device class associated with the specified phone device.

LONG TSPIAPI TSPI_phoneGetID(
  HDRVPHONE hdPhone,
  LPVARSTRING lpDeviceID,
  LPCWSTR lpszDeviceClass,
  HANDLE hTargetProcess
);

Parameters

hdPhone
The handle to the phone to be queried.
lpDeviceID
A pointer to a data structure of type VARSTRING where the device identifier is returned. The format of the returned information depends on the method used by the device class (API) for naming devices. Prior to calling TSPI_phoneGetID, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.
lpszDeviceClass
A pointer to a null-terminated Unicode string that specifies the device class of the device whose identifier is requested.
hTargetProcess
The process handle of the application on behalf of which the TSPI_phoneGetID function is being invoked. If the information being returned in the VARSTRING structure includes a handle for use by the application, the service provider creates or duplicates the handle for the process.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

This operation can be used to retrieve a phone device identifier given a phone handle. It can also be used to obtain the device identifier of the media device (for device classes such as COM, wave, MIDI, phone, line, and mciwave) associated with the opened phone device. This identifier can then be used with the appropriate media API (such as mci, midi, and wav) to select the corresponding device. For more information about common device class names, see TSPI Device Classes.

The service provider fills in all the members of the VARSTRING data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

The service provider does not need to be concerned with handling tapi/line and tapi/phone device classes because TAPI handles these for the service provider. Therefore, code for handling these device classes is optional.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

VARSTRING


TSPI_phoneGetLamp

The TSPI_phoneGetLamp function returns the current lamp mode of the specified lamp.

LONG TSPIAPI TSPI_phoneGetLamp(
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  LPDWORD lpdwLampMode
);

Parameters

hdPhone
The handle to the phone whose lamp mode is to be retrieved.
dwButtonLampID
The identifier of the lamp to be queried.
lpdwLampMode
A pointer to a memory location into which the service provider writes the lamp mode status of the given lamp. This parameter can have at most one of the PHONELAMPMODE_ constants.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

Phone sets that have multiple lamps per button should be modeled using multiple button/lamps pairs. Each additional button/lamp pair should use a DUMMY button.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONECAPS, PHONELAMPMODE_ Constants, TSPI_phoneGetDevCaps, TSPI_phoneSetLamp


TSPI_phoneGetRing

The TSPI_phoneGetRing function enables an application to query the specified open phone device as to its current ring mode.

LONG TSPIAPI TSPI_phoneGetRing(
  HDRVPHONE hdPhone,
  LPDWORD lpdwRingMode,
  LPDWORD lpdwVolume
);

Parameters

hdPhone
The handle to the phone whose ring mode is to be queried.
lpdwRingMode
The ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.
lpdwVolume
The volume level with which the phone is ringing. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of phone's ring modes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetRing


TSPI_phoneGetStatus

The TSPI_phoneGetStatus function queries the specified open phone device for its overall status.

LONG TSPIAPI TSPI_phoneGetStatus(
  HDRVPHONE hdPhone,
  LPPHONESTATUS lpPhoneStatus
);

Parameters

hdPhone
The handle to the phone to be queried.
lpPhoneStatus
A pointer to a variably sized data structure of type PHONESTATUS, into which the service provider writes information about the phone's status. Prior to calling TSPI_phoneGetStatus, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

The following table indicates which members of the PHONESTATUS data structure are filled in by TAPI and which members are filled in by the service provider. The service provider must not overwrite the values filled in by TAPI.

Member | TAPI | Service provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
dwStatusFlags; |  | X
dwNumOwners; | X |
dwNumMonitors; | X |
dwRingMode; |  | X
dwRingVolume; |  | X
dwHandsetHookSwitchMode; |  | X
dwHandsetVolume; |  | X
dwHandsetGain; |  | X
dwSpeakerHookSwitchMode; |  | X
dwSpeakerVolume; |  | X
dwSpeakerGain; |  | X
dwHeadsetHookSwitchMode; |  | X
dwHeadsetVolume; |  | X
dwHeadsetGain; |  | X
dwDisplaySize; |  | X
dwDisplayOffset; |  | X
dwLampModesSize; |  | X
dwLampModesOffset; |  | X
dwOwnerNameSize; | X |
dwOwnerNameOffset; | X |
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

TAPI can use this function to determine the current state of an open phone device. The status information describes information about the phone device's hookswitch devices, ringer, volume, display, and lamps of the open phone.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONE_STATE, PHONESTATUS


TSPI_phoneGetVolume

The TSPI_phoneGetVolume function returns the volume setting of the specified phone's hookswitch device.

LONG TSPIAPI TSPI_phoneGetVolume(
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwVolume
);

Parameters

hdPhone
The handle to the phone containing the hookswitch device whose volume setting is to be retrieved.
dwHookSwitchDev
Identifies a single hookswitch device whose volume level is queried. This parameter uses one of the PHONEHOOKSWITCHDEV_ constants.
lpdwVolume
A pointer to a DWORD-sized location into which the service provider writes the current volume setting of the hookswitch device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, HONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetVolume


TSPI_phoneNegotiateExtVersion

The TSPI_phoneNegotiateExtVersion function returns the highest extension version number the service provider can operate under for this device, given the range of possible extension versions.

LONG TSPIAPI TSPI_phoneNegotiateExtVersion(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

dwDeviceID
Identifies the phone device for which interface version negotiation is to be performed.
dwTSPIVersion
Specifies an interface version number that is negotiated for this device using TSPI_phoneNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
dwLowVersion
The lowest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
dwHighVersion
The highest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
lpdwExtVersion
A pointer to a DWORD. Upon a successful return from this function, the service provider fills this location with the highest extension version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns PHONEERR_INCOMPATIBLEEXTVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_NODRIVER, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

This function can be called before or after the device has been opened by TAPI. If the device is currently open and has an extension version selected, the function should return that version number if it is within the requested range. If the selected version number is outside the requested range, the function returns PHONEERR_INCOMPATIBLEEXTVERSION.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

TSPI_phoneNegotiateTSPIVersion


TSPI_phoneNegotiateTSPIVersion

The TSPI_phoneNegotiateTSPIVersion function returns the highest SPI version the service provider can operate under for this device, given the range of possible SPI versions.

LONG TSPIAPI TSPI_phoneNegotiateTSPIVersion(
  DWORD dwDeviceID,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwTSPIVersion
);

Parameters

dwDeviceID
The phone device for which interface version negotiation is to be performed. Permitted values are strictly within the range of phone devices identifiers for this service provider; the value INITIALIZE_NEGOTIATION is never passed to this function.
dwLowVersion
The lowest TSPI version number under which TAPI can operate. The most significant WORD is the major version number and the least significant WORD is the minor version number.
dwHighVersion
The highest TSPI version number under which TAPI can operate. The most significant WORD is the major version number and the least significant WORD is the minor version number.
lpdwTSPIVersion
A pointer to a DWORD. Upon a successful return from this function the service provider fills this location with the highest TSPI version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns PHONEERR_INCOMPATIBLEAPIVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

The service provider returns PHONEERR_OPERATIONUNAVAIL if the operation is not available. However, if the service provider supports any phone devices, it must also support this function and the function must not return PHONEERR_OPERATIONUNAVAIL.

TAPI calls this function early in the initialization sequence for each phone device.

Negotiation of an extension version is done through the separate procedure TSPI_phoneNegotiateExtVersion.

The corresponding function at the TAPI level is an overloaded function that also retrieves the extension identifier, if any, supported by the service provider. At the TSPI level, retrieving the extension identifier is accomplished through a separate procedure, namely, TSPI_phoneGetExtensionID.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

INITIALIZE_NEGOTIATION, TSPI_phoneGetExtensionID, TSPI_phoneNegotiateExtVersion


TSPI_phoneOpen

The TSPI_phoneOpen function opens the phone device whose device identifier is given, returning the service provider's opaque handle for the device and retaining TAPI's opaque handle for the device for use in subsequent calls to the PHONEEVENT procedure.

LONG TSPIAPI TSPI_phoneOpen(
  DWORD dwDeviceID,
  HTAPIPHONE htPhone,
  LPHDRVPHONE lphdPhone,
  DWORD dwTSPIVersion,
  PHONEEVENT lpfnEventProc
);

Parameters

dwDeviceID
The phone device to be opened.
htPhone
The TAPI opaque handle for the phone device to be used in subsequent calls to the PHONEEVENT callback procedure to identify the device.
lphdPhone
A pointer to an HDRVPHONE where the service provider writes its handle for the phone device to be used by TAPI in subsequent calls to identify the device.
dwTSPIVersion
The TSPI version negotiated through TSPI_phoneNegotiateTSPIVersion under which the service provider can operate.
lpfnEventProc
A pointer to the PHONEEVENT callback procedure supplied by TAPI that the service provider calls to report subsequent events on the phone.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_ALLOCATED, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_OPERATIONFAILED, PHONEERR_INUSE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INIFILECORRUPT.

Remarks

Opening a phone entitles TAPI to make further requests on the phone. The phone becomes active in the sense that the service provider can report asynchronous events such as hookswitch changes or button presses. The service provider reserves whatever nonsharable resources are required to manage the phone. For example, opening a phone accessed through a comm port and modem should result in opening the comm port, making it no longer available for use by other applications.

If the function succeeds, both TAPI and the service provider become committed to operating under the specified interface version number for this open device. Subsquent operations and events identified using the exchanged opaque phone handles conform to that interface version. This commitment and the validity of the handles remain in effect until TAPI closes the phone using TSPI_phoneClose or until the service provider reports the PHONE_CLOSE event. If the function is not successful, no such commitment is made and the handles are not valid.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONE_CLOSE, PHONEEVENT, TSPI_phoneClose, TSPI_phoneNegotiateTSPIVersion


TSPI_phoneSelectExtVersion

The TSPI_phoneSelectExtVersion function selects the indicated extension version for the indicated phone device. Subsequent requests operate according to that extension version.

LONG TSPIAPI TSPI_phoneSelectExtVersion(
  HDRVPHONE hdPhone,
  DWORD dwExtVersion
);

Parameters

hdPhone
The handle to the phone for which an extension version is to be selected.
dwExtVersion
The extension version to be selected. This version number is negotiated using TSPI_phoneNegotiateExtVersion. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. Calling this function with a dwExtVersion of zero cancels the current selection.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

This function selects the indicated extension version. Although the indicated version number may have been successfully negotiated, a different extension version may have been selected in the interim, in which case this function fails (returning PHONEERR_INCOMPATIBLEEXTVERSION).

Subsequent operations on the phone after an extension version is selected behave according to that extension version. Subsequent attempts to negotiate the extension version report strictly the selected version or zero (if the requested range does not include the selected version). Calling this procedure with the special extension version 0 cancels the current selection. The device once again becomes capable of supporting its full range of extension version numbers.

TSPI_phoneSelectExtVersion is typically called in two situations: (1) An application requested to open a phone, the application requested that a particular extension version be used, and no extension version was currently selected; or (2) the last application using a particular extension version closed the phone, and the extension version selection can be canceled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_phoneNegotiateExtVersion


TSPI_phoneSetButtonInfo

The TSPI_phoneSetButtonInfo function sets information about the specified button on the specified phone.

LONG TSPIAPI TSPI_phoneSetButtonInfo(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO const lpButtonInfo
);

Parameters

dwRequestID
The identifier of the asynchronous request. The service provider returns this value if the function completes asynchronously.
hdPhone
The handle to the phone for which button info is to be set.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode and function, and provides additional descriptive text to be set for the button.

Return Values

Returns the (positive) dwRequestID value if the function is completed asynchronously, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONLAMPID, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

This function sets the meaning and associated descriptive text of a phone's buttons.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONEBUTTONINFO, PHONECAPS, TSPI_phoneGetButtonInfo


TSPI_phoneSetData

The TSPI_phoneSetData function downloads the information in the specified buffer to the opened phone device at the selected data identifier.

LONG TSPIAPI TSPI_phoneSetData(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwDataID,
  LPVOID const lpData,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone into which data is to be downloaded.
dwDataID
Specifies where in the phone device the buffer is to be downloaded.
lpData
A pointer to the memory location where the data is to be downloaded from.
dwSize
The size of the buffer in bytes.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALDATAID, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The function downloads a maximum of dwSize bytes from lpData to the phone device. The format of the data, its meaning to the phone device, and the meaning of the data identifier are service-provider specific. The data in the buffer or the selection of a data identifier can act as commands to the phone device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetData, TSPI_phoneGetDevCaps


TSPI_phoneSetDisplay

The TSPI_phoneSetDisplay function causes the specified string to be displayed on the specified open phone device.

LONG TSPIAPI TSPI_phoneSetDisplay(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwRow,
  DWORD dwColumn,
  LPCWSTR lpsDisplay,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone on which the string is to be displayed.
dwRow
The row on the display where the new text is to be displayed.
dwColumn
The column position on the display where the new text is to be displayed.
lpsDisplay
A pointer to the memory location where the display content is stored. The application stores the display information in the format specified as dwStringFormat in the phone's PHONECAPS structure.
dwSize
The size in bytes of the information pointed to by lpDisplay.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The specified display information is written to the phone's display, starting at the specified positions. This operation overwrites previously displayed information. If the amount of information exceeds the size of the display, the information is truncated. The amount of information that can be displayed is at most (dwNumRows * dwNumColumns) elements in size. The dwNumRows and dwNumColumns members are available in the PHONECAPS structure returned by TSPI_phoneGetDevCaps; they are zero-based.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneGetDisplay


TSPI_phoneSetGain

The TSPI_phoneSetGain function sets the gain of the microphone of the specified hookswitch device to the specified gain level.

LONG TSPIAPI TSPI_phoneSetGain(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  DWORD dwGain
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone containing the hookswitch device whose gain is to be set.
dwHookSwitchDev
The hookswitch device whose microphone's gain is to be set. This parameter uses one and only one of the PHONEHOOKSWITCHDEV_ Constants.
dwGain
A DWORD-sized location containing the desired new gain setting of the device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service-provider-specific. A value for dwGain that is out of range is clamped by TAPI to the nearest in-range value.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetGain


TSPI_phoneSetHookSwitch

The TSPI_phoneSetHookSwitch function sets the hook state of the specified open phone's hookswitch devices to the specified mode. Only the hookswitch state of the hookswitch devices listed is affected.

LONG TSPIAPI TSPI_phoneSetHookSwitch(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDevs,
  DWORD dwHookSwitchMode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone containing the hookswitch devices whose modes are to be set.
dwHookSwitchDevs
The device(s) whose hookswitch mode is to be set. This parameter uses one of the PHONEHOOKSWITCHDEV_ constants.
dwHookSwitchMode
The hookswitch mode to set. This parameter can have only one of the PHONEHOOKSWITCHMODE_ constants.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALHOOKSWITCHMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL.

Remarks

The hookswitch mode is changed to the indicated setting for all devices specified. If different settings are desired, this function can be invoked multiple times with a different set of parameters. A PHONE_STATE message is sent to the application after the hookswitch state has changed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONE_STATE, PHONESTATUS, PHONEHOOKSWITCHDEV_ Constants, PHONEHOOKSWITCHMODE_ Constants, TSPI_phoneGetHookSwitch


TSPI_phoneSetLamp

The TSPI_phoneSetLamp function causes the specified lamp to be set on the specified open phone device in the specified lamp mode.

LONG TSPIAPI TSPI_phoneSetLamp(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  DWORD dwLampMode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone whose lamp is to be set.
dwButtonLampID
The button whose lamp is to be set.
dwLampMode
Specifies how the lamp is to be lit. The dwLampMode parameter can only have one of the PHONELAMPMODE_ constants.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALLAMPMODE, PHONEERR_OPERATIONUNAVAIL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONELAMPMODE_ Constants, TSPI_phoneGetDevCaps, TSPI_phoneGetLamp


TSPI_phoneSetRing

The TSPI_phoneSetRing function rings the specified open phone device using the specified ring mode and volume.

LONG TSPIAPI TSPI_phoneSetRing(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwRingMode,
  DWORD dwVolume
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone to be rung.
dwRingMode
The ringing pattern with which to ring the phone. This parameter must be within the range from zero through the value of the dwNumRingModes member in the PHONECAPS structure. If dwNumRingModes is zero, the ring mode of the phone cannot be controlled; if dwNumRingModes is 1, a value of 0 for dwRingMode indicates that the phone should not be rung (silence), and other values from 1 through dwNumRingModes are valid ring modes for the phone device.
dwVolume
The volume level with which the phone is to be rung. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific. A value for dwVolume that is out of range is clamped by TAPI to the nearest value in range.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALRINGMODE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneGetRing


TSPI_phoneSetStatusMessages

The TSPI_phoneSetStatusMessages function causes the service provider to filter status messages that are not currently of interest to any application.

LONG TSPIAPI TSPI_phoneSetStatusMessages(
  HDRVPHONE hdPhone,
  DWORD dwPhoneStates,
  DWORD dwButtonModes,
  DWORD dwButtonStates
);

Parameters

hdPhone
The opaque handle to the phone whose state-change monitoring filter is to be set.
dwPhoneStates
Flags that specify the set of phone status changes and events for which TAPI wants to receive notification messages. This parameter can have zero, one, or more than one of the PHONESTATE_ constants.
dwButtonModes
Flags that specify the set of phone button modes for which TAPI wants to receive notification messages. If dwButtonModes is zero, dwButtonStates is ignored. This parameter can have zero, one, or more than one of the PHONEBUTTONMODE_ constants. If dwButtonModes has at least one of these flags set, dwButtonStates must also have at least one bit set:
dwButtonStates
This parameter specifies the set of phone button state changes for which TAPI wishes to receive notification messages, one of the PHONEBUTTONSTATE_ Constants.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONSTATE, PHONEERR_OPERATIONUNAVAIL.

Remarks

TAPI defines a number of messages that notify applications about events occurring on phones. The sets of all change messages in which all applications are interested can be much smaller than the set of possible messages. This procedure allows TAPI to tell the service provider the reduced set of messages to deliver. The service provider delivers all of the messages it supports, within the specified set. It is permitted to deliver more (they are filtered out by TAPI), but is discouraged from doing so for performance reasons. If TAPI requests delivery of a particular message type that is not produced by the provider, the provider nevertheless accepts the request but simply does not produce the message. All phone status messages except PHONESTATE_REINIT are disabled by default.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

PHONE_BUTTON, PHONE_STATE, PHONESTATE_ Constants


TSPI_phoneSetVolume

The TSPI_phoneSetVolume function sets the volume of the speaker component of the specified hookswitch device to the specified level.

LONG TSPIAPI TSPI_phoneSetVolume(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  DWORD dwVolume
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone containing the speaker whose volume is to be set.
dwHookSwitchDev
Identifies the hookswitch device whose speaker's volume is to be set. This parameter uses one of the PHONEHOOKSWITCHDEV_ constants.
dwVolume
A DWORD specifying the new volume level of the hookswitch device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific. A value for dwVolume that is out of range is clamped by TAPI to the nearest value in range.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

None.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, PHONECAPS, PHONEHOOKSWITCHDEV_ Constants, TSPI_phoneGetDevCaps, TSPI_phoneSetVolume


TSPI Callback Functions

This section contains descriptions of the Telephony SPI callback functions. The TSPI callback functions include:

  • ASYNC_COMPLETION
  • LINEEVENT
  • PHONEEVENT


ASYNC_COMPLETION

This type is a callback function implemented by TAPI and supplied to the service provider as a parameter to TSPI_providerInit. The service provider calls this function to report the completion of a line or phone procedure that it executes asynchronously.

ASYNC_COMPLETION Completion_Proc;
void(
  CALLBACK* Completion_Proc)(
  DRV_REQUESTID dwRequestID,
  LONG lResult
);

Parameters

dwRequestID
The identifier passed in the original request that the service provider executed asynchronously.
lResult
The outcome of the operation. This can be zero to indicate success or a negative number to indicate an error. The possible specific error values that can result from a function are the same for asynchronous or synchronous execution.

Return Values

No return value.

Remarks

The call state when calling this function can be any state.

This procedure is supplied by TAPI at the time a service provider is initialized with the TSPI_providerInit function. Some of the TSPI procedures that operate on line, call, and phone devices specify asynchronous operation. These procedures include a dwRequestID parameter to identify the request. When such a procedure is called, the service provider can return a negative number for an error if one is detected immediately, or the positive dwRequestID if the operation continues asynchronously. The service provider must report completion exactly once for each request it executes asynchronously. It does so by calling this procedure. The service provider is not permitted to call this procedure or the LINEEVENT or PHONEEVENT procedure again until this procedure returns.

The service provider is permitted to call the ASYNC_COMPLETION function before it returns from the first request. TAPI guarantees not to call the service provider from within the ASYNC_COMPLETION context except where noted.

This does not have any direct correspondence at the TAPI level because at that level asynchronous function completions are reported as a message passed through the same callback interface that is used for spontaneous event messages. At the TSPI level, spontaneous events are reported through the LINEEVENT and PHONEEVENT callback procedures.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINEEVENT, PHONEEVENT, TSPI_providerInit


LINEEVENT

This type is a callback function implemented by TAPI and supplied to the service provider as a parameter to TSPI_lineOpen. The service provider calls this function to report events that occur on the line or on calls on the line.

LINEEVENT Line_Event;
void(
  CALLBACK * Line_Event)(
  HTAPILINE htLine,
  HTAPICALL htCall,
  DWORD dwMsg,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

htLine
The TAPI handle for the line on which the event occurred.
htCall
The TAPI handle for the call on which the event occurred if this is a call-related event. For line-related events where there is no call, this parameter is set to NULL.
dwMsg
Specifies the kind of event that is being reported. Interpretation of the other parameters is performed in different ways according to the context indicated by dwMsg.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Return Values

No return value.

Remarks

The call state when calling this function can be any state.

The service provider passes the HTAPILINE value supplied to TSPI_lineOpen as the htLine parameter. It includes the message identifier and parameters specific to the event.

This function differs from the callback function defined at the TAPI level in that it separates line and call parameters. Both parameters are used for some messages. The sets of messages that can be passed to this procedure differ slightly from the TAPI level. In particular, completion of asynchronously executing requests is reported through the ASYNC_COMPLETION callback instead of this one.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, TSPI_lineOpen


PHONEEVENT

This type is a callback function implemented by TAPI and supplied to the service provider as a parameter to TSPI_phoneOpen. The service provider calls this function to report events that occur on the phone.

PHONEEVENT Phone_Event;
void(
  CALLBACK *Phone_Event)(
  HTAPIPHONE htPhone,
  DWORD dwMsg,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

htPhone
The TAPI handle for the phone on which the event occurred.
dwMsg
Specifies the kind of event that is being reported. Interpretation of the other parameters is done in different ways according to the context indicated by dwMsg.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Return Values

No return value.

Remarks

The call state when calling this function can be any state.

The service provider passes the HTAPIPHONE value supplied to TSPI_phoneOpen as the htPhone parameter. It includes the message identifier and parameters specific to the event.

The sets of messages that can be passed to this procedure differ slightly from the messages to the corresponding callback at the TAPI level. In particular, completion of asynchronously executing requests is reported through the ASYNC_COMPLETION callback instead of this one.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

ASYNC_COMPLETION, TSPI_lineOpen


TSP UI DLL Functions

This section describes the Telephony Service Provider User Interface (UI) DLL functions. The TSP UI DLL functions include:

  • TSPI_providerFreeDialogInstance
  • TSPI_providerGenericDialogData
  • TSPI_providerUIIdentify


TSPI_providerFreeDialogInstance

The TSPI_providerFreeDialogInstance function informs the service provider that the dialog box associated with hdDlgInst has exited. After this function is called, the service provider should no longer send data to the dialog box using LINE_SENDDIALOGINSTANCEDATA messages.

Implementation of this function is optional; it is needed only if the service provider generates spontaneous dialog boxes in application contexts using LINE_CREATEDIALOGINSTANCE.

LONG TSPIAPI TSPI_providerFreeDialogInstance(
  HDRVDIALOGINSTANCE hdDlgInst
);

Parameters

hdDlgInst
The opaque identifier of the association between the service provider and the dialog box in the application's context, which was passed as the hdDlgInstance member in the TUISPICREATEDIALOGINSTANCEPARAMS structure with the LINE_CREATEDIALOGINSTANCE message that created the dialog box.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CREATEDIALOGINSTANCE, LINE_SENDDIALOGINSTANCEDATA, TUISPICREATEDIALOGINSTANCEPARAMS


TSPI_providerGenericDialogData

The TSPI_providerGenericDialogData function delivers to the service provider data that was sent from the UI DLL running in an application context through the TUISPIDLLCALLBACK function. The contents of the memory block pointed to by lpParams is defined by the service provider and UI DLL. The service provider can modify the contents of the parameter block; when this function returns, TAPI copies the modified data back into the original UI DLL parameter block.

Implementation is mandatory if the UI DLL associated with the service provider calls TUISPIDLLCALLBACK.

LONG TSPIAPI TSPI_providerGenericDialogData(
  DWORD_PTR dwObjectID,
  DWORD dwObjectType,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwObjectID
An object identifer of the type specified by dwObjectType.
dwObjectType
One of the TUISPIDLL_OBJECT_ constants, specifying the type of object identified by dwObjectID:
TUISPIDLL_OBJECT_LINEID
dwObjectID is a line device identifier (dwDeviceID).
TUISPIDLL_OBJECT_PHONEID
dwObjectID is a phone device identifier (dwDeviceID)
TUISPIDLL_OBJECT_PROVIDERID
dwObjectID is a permanent provider identifier.
TUISPIDLL_OBJECT_DIALOGINSTANCE
dwObjectID is an HDRVDIALOGINSTANCE, as returned to the service provider when it sent a LINE_CREATEDIALOGINSTANCE message.
lpParams
Pointer to a memory area used to hold a parameter block. The contents of this parameter block are specific to the service provider and its associated UI DLL.
dwSize
The size in bytes of the parameter block.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CREATEDIALOGINSTANCE, TUISPIDLLCALLBACK


TSPI_providerUIIdentify

The TSPI_providerUIIdentify function extracts from the service provider the fully qualified path to load the service provider's UI DLL component.

Implementation is mandatory if the service provider implements any UI DLL functions.

LONG TSPIAPI TSPI_providerUIIdentify(
  LPWSTR lpszUIDLLName
);

Parameters

lpszUIDLLName
Pointer to a block of memory at least MAX_PATH in length, into which the service provider must copy a null-terminated string specifying the fully qualified path for the DLL containing the service provider functions which must execute in the process of the calling application.

Return Values

Returns zero if successful. Shouldn't ever fail, but if it does returns one of these negative error values:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.


TUISPI Service Provider Functions

This section contains an alphabetic list of the Telephony User Interface Service Provider functions. The TUISPI service provider functions include:

  • TUISPI_providerConfig
  • TUISPI_providerGenericDialog
  • TUISPI_providerGenericDialogData
  • TUISPI_providerInstall
  • TUISPI_providerRemove


TUISPI_providerConfig

The TUISPI_providerConfig function implements the UI elements that must execute in the context of the calling application. This function makes the TSPI_providerConfig function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

The TUISPI_providerConfig function gathers configuration information from the user. It can use a dialog box, and this dialog box can include sub-dialog boxes associated with other APIs (such as Comm/datamodem) for the setup of specific devices.

Implementation is optional.

LONG TSPIAPI TUISPI_providerConfig(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box and to send updated configuration to the service provider.
hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the configuration.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_NOMEM.

Remarks

This function may be called while the service provider is in use (that is, between calls of TSPI_providerInit and TSPI_providerShutdown).

Any changes that affect the behavior visible through TSPI should take effect only when the service provider is restarted at the next TSPI_providerInit.

There is no directly corresponding function at the TAPI level. In TAPI, applications have access to the functions lineConfigDialog and phoneConfigDialog, which allow configuration of parameters of a particular line or phone once it has been installed.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TUISPI_lineConfigDialog, TUISPI_phoneConfigDialog, TUISPI_providerInstall, TUISPI_providerRemove


TUISPI_providerGenericDialog

The TUISPI_providerGenericDialog function in the UI DLL is called when the service provider sends a LINE_CREATEDIALOGINSTANCE message. The service provider uses this to create dialog boxes in the application context in conjunction with the processing of particular asynchronous TSPI functions. This function is called from a thread created specifically for the purpose of displaying the dialog box. The UI DLL does not return from this function until the dialog box is destroyed.

Implementation is mandatory if the service provider associated with the UI DLL sends LINE_CREATEDIALOGINSTANCE messages to spontaneously create dialog boxes in the application context.

LONG TSPIAPI TUISPI_providerGenericDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HTAPIDIALOGINSTANCE htDlgInst,
  LPVOID lpParams,
  DWORD dwSize,
  HANDLE hEvent
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
htDlgInst
The opaque identifier binding the association of this instance of the function to a particular request from the service provider. The UI DLL must include this parameter, along with TUISPI_OBJECT_DIALOGINSTANCE, in any call to TUISPIDLLCALLBACK to request further data from or deliver data to the service provider.
lpParams
Pointer to a memory area used to hold a parameter block. The contents of this parameter block are specific to the service provider and its associated UI DLL. The conveyance of data through this parameter block is one-way to the UI DLL; changes made to the parameter block are not reflected back in the service provider. Generally, this parameter block holds all information the UI DLL needs to initially display the dialog box.
dwSize
The size in bytes of the parameter block.
hEvent
Handle to an event object created by TAPI. This event is signaled by the UI DLL through SetEvent (hEvent) when the UI DLL has completed initialization of this dialog box instance and is prepared to receive additional dialog box data through TUISPI_providerGenericDialogData. Data sent by the associated service provider (through LINE_SENDDIALOGINSTANCEDATA) for this dialog box instance are blocked by TAPI until the UI DLL signals this event, giving TUISPI_providerGenericDialog the opportunity to perform any necessary initialization. The UI DLL should signal the event as quickly a possible to avoid blocking calls to TUISPI_providerGenericDialogData.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CREATEDIALOGINSTANCE, TUISPIDLLCALLBACK, SetEvent, TUISPI_providerGenericDialogData, LINE_SENDDIALOGINSTANCEDATA


TUISPI_providerGenericDialogData

The TUISPI_providerGenericDialogData function in the UI DLL is called when the service provider sends a LINE_SENDDIALOGINSTANCEDATA message. The service provider uses this to spontaneously update information in dialog boxes created in the application context in conjunction with the processing of particular asynchronous TSPI functions. This function is called from a separate thread from that in which TSPI_providerGenericDialogData is executing. The UI DLL should not block the thread in which this function is called, but should process the data and return immediately (posting a message to the dialog box if necessary).

Implementation is mandatory if TUISPI_providerGenericDialog is exported.

LONG TSPIAPI TUISPI_providerGenericDialog(
  HTAPIDIALOGINSTANCE htDlgInst,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

htDlgInst
The opaque identifier binding the association of this instance of the function to a particular request from the service provider.
lpParams
Pointer to a memory area used to hold a parameter block. The contents of this parameter block are specific to the service provider and its associated UI DLL. The conveyance of data through this parameter block is one-way to the UI DLL; changes made to the parameter block are not reflected back in the service provider. If this parameter is set to NULL, this is a request to close the dialog box immediately and clean up (TUISPIDLLCALLBACK should not be invoked during this cleanup). TAPI invokes this function with lpParams set to NULL to force dialog box cleanup under certain circumstances, such as an application calling lineShutdown with a dialog box still active.
dwSize
The size in bytes of the parameter block.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_SENDDIALOGINSTANCEDATA, TUISPIDLLCALLBACK, lineShutdown


TUISPI_providerInstall

Implementation of the TUISPI_providerInstall function is the service provider's opportunity to install any additional "pieces" of the provider into the right directories (or at least verifying that they're there) and set up registry entries the provider needs. This function makes the TSPI_providerInstall function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

If the service provider requires any privately-defined entries in the registry for proper operation, they must be installed at this time.

Implementation is optional.

LONG TSPIAPI TUISPI_providerInstall(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
hwndOwner
The handle of the parent window in which the function can create any dialog box windows that are required during installation.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM. LINEERR_INVALPARAM.

Remarks

This function must leave the system in a consistent state. It should run to completion, not allowing the user to abort the installation when it is partly completed. If installation fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete installation is possible, before the installation begins.

This function can be invoked more than once during installation of the service provider, until there is a call to TUISPI_providerRemove. If the service provider does not require or support multiple instances of the provider, however, it returns the LINEERR_ constant LINEERR_NOMULTIPLEINSTANCE.

The corresponding function at the TAPI level is lineAddProvider. The LINE_CREATE message informs applications that are running about dynamic reconfiguration.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CREATE, PHONE_STATE, TUISPI_providerConfig, TSPI_providerInit, TUISPI_providerRemove, TSPI_providerShutdown


TUISPI_providerRemove

The TUISPI_providerRemove function asks the user to confirm elimination of the service provider. This function makes the TSPI_providerRemove function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

It is the responsibility of the service provider to remove any registry entries that the service provider added at addProvider time, as well as any other modules and files that are no longer needed.

Implementation is optional.

LONG TSPIAPI TUISPI_providerRemove(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the removal.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarks

This function must guarantee that any service provider's privately-defined information is removed from the registry if it returns success.

This procedure must leave the system in a consistent state. It should run to completion, not allowing the user to abort the removal when it is partly completed. If removal fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete removal is possible, before the removal begins.

This function can be called while the service provider is in use (that is, between TSPI_providerInit and TSPI_providerShutdown). If this happens, the service provider should do an appropriate combination of displaying a user dialog box to announce any conflict and confirm removal, restricting removal options to those that can be performed transparently, or issuing LINE_CLOSE and PHONE_CLOSE messages to inform TAPI and applications that the affected devices have been forcibly closed for removal. In any case, any changes that affect the behavior visible through TSPI should take effect only when the service provider is shut down at the next TSPI_providerShutdown.

Note This function should not return LINEERR_INUSE or other errors that might occur because the provider is in use by an application; instead, the provider should confer with the user directly about this problem, and then return LINEERR_OPERATIONFAILED if the user decides to abort the operation.

This procedure is called only once, at the time of removal of the service provider, until there is a call to TUISPI_providerInstall.

The corresponding function at the TAPI level is lineRemoveProvider. At that level, applications expect to have service providers already installed; otherwise their lines and phones do not appear within the available sequence of device identifiers. The LINE_CREATE message informs applications that are running about dynamic reconfiguration.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CLOSE, PHONE_CLOSE, PHONE_STATE, TSPI_providerInit, TSPI_providerShutdown, TUISPI_providerInstall


TUISPI Line Device Functions

This section contains an alphabetic list of the TUISPI line device functions. The TUISPI line device functions include:

  • TUISPI_lineConfigDialog
  • TUISPI_lineConfigDialogEdit


TUISPI_lineConfigDialog

The TUISPI_lineConfigDialog function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device. This function makes the TSPI_lineConfigDialog function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

Implementation is optional.

LONG TSPIAPI TUISPI_lineConfigDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box and to send updated configuration to the service provider.
dwDeviceID
The line device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a null-terminated string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box should be selected. The permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters.)

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

There is no restriction that TUISPI_lineConfigDialog be called only when the line is closed. However, each provider can impose such a restriction itself. When TUISPI_lineConfigDialog is called, the provider could alert the user with the message "The line is in use by one or more applications. You may not change the line configuration while the line is in use" (and return the error message LINEERR_INUSE). However, some configurations may be safe to change "on the fly," particularly those related to media types (such as the modem error control protocol), especially when that media type is not currently in use. The provider could allow those options to be changed while the line is open.

Users should not be allowed to change anything that alters values returned with LINEDEVCAPS or LINEADDRESSCAPS without first forcibly closing the line as a signal that applications must call functions that return these structures in order to have accurate information.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig


TUISPI_lineConfigDialogEdit

The TUISPI_lineConfigDialogEdit function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device. This function makes the TSPI_lineConfigDialogEdit function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

Implementation is optional.

LONG TSPIAPI TUISPI_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD dwSize,
  LPVARSTRING lpDeviceConfigOut
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached.
lpszDeviceClass
A pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or points to an empty string, the highest level configuration is selected. The permitted strings are the same as for TSPI_lineGetID.
lpDeviceConfigIn
A pointer to the opaque configuration data structure that was returned by TSPI_lineGetDevConfig (or a previous invocation of TUISPI_lineConfigDialogEdit) in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfigIn. This value is returned in the dwStringSize member in the VARSTRING structure returned by TSPI_lineGetDevConfig or a previous invocation of TUISPI_lineConfigDialogEdit.
lpDeviceConfigOut
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig (or a future invocation of lineConfigDialogEdit), the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM.

Remarks

The lpszDeviceClass parameter selects a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter is "tapi/line", "", or NULL to cause the provider to display the highest level configuration for the line.

The difference between this function and TUISPI_lineConfigDialog is the source of the parameters to edit and the result of the editing. In TUISPI_lineConfigDialog, the parameters edited are those currently in use on the device (or set for use on the next call), and any changes made have (to the maximum extent possible) an immediate impact on any active connection; also, the application must use lineGetDevConfig to fetch the result of parameter changes from TUISPI_lineConfigDialog. With TUISPI_lineConfigDialogEdit, the parameters to edit are passed in from the application, and the results are returned to the application, with no impact on active connections; the results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, TUISPI_lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. However, the output of this function can be passed to TSPI_lineSetDevConfig to affect the current call or next call.

For backward compatibility, this function is not exported by older service providers. TAPI detects this condition and reports LINEERR_OPERATIONUNAVAIL if an application attempts to call this function on an older provider.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig, TUISPI_lineConfigDialog, VARSTRING


TUISPI Phone Device Functions

This section contains the TUISPI phone device function, which is:

  • TUISPI_phoneConfigDialog


TUISPI_phoneConfigDialog

The TUISPI_phoneConfigDialog function causes the provider of the specified phone device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the phone device.This function makes the TSPI_phoneConfigDialog function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

Implementation is optional.

LONG TSPIAPI TUISPI_phoneConfigDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box and to send updated configuration to the service provider.
dwDeviceID
The phone device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a null-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box is selected.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INUSE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_RESOURCEUNAVAIL.

Remarks

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested. The permitted strings are the same as for TSPI_phoneGetID.

For example, if the phone supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters). The szDeviceClass parameter should be "tapi/phone", "", or NULL to cause the provider to display the highest level configuration for the phone.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

PHONECAPS, TSPI_phoneGetID


TUISPI Callback Functions

This section contains the description of the TUISPI callback function, which is:

  • TUISPIDLLCALLBACK


TUISPIDLLCALLBACK

The TUISPIDLLCALLBACK function is called by the UI DLL to send a private parameter block to the service provider. Each invocation of the callback results in a call to the TSPI_providerGenericDialogData function in the service provider associated with the specified object. The contents of the parameter block are defined by the service provider and UI DLL. The service provider can modify the contents of the parameter block; when this function returns, TAPI copies the modified data back into the original UI DLL parameter block.

typedef LONG (CALLBACK * TUISPIDLLCALLBACK) (
  DWORD dwObjectID,
  DWORD dwObjectType,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwObjectID
An object identifer of the type specified by dwObjectType.
dwObjectType
One of the TUISPIDLL_OBJECT_ constants, specifying the type of object identified by dwObjectID.
TUISPIDLL_OBJECT_LINEID
The dwObjectID parameter is a line device identifier (dwDeviceID). This is used when the callback is invoked during the processing of TUISPI_lineConfigDialog or TUISPI_lineConfigDialogEdit.
TUISPIDLL_OBJECT_PHONEID
The dwObjectID parameter is a phone device identifier (dwDeviceID). This is used when the callback is invoked during the processing of TUISPI_phoneConfigDialog.
TUISPIDLL_OBJECT_PROVIDERID
The dwObjectID parameter is a permanent provider identifier. This is used when the callback is invoked during the processing of TUISPI_providerConfig, TUISPI_providerInstall, or TUISPI_providerRemove.
TUISPIDLL_OBJECT_DIALOGINSTANCE
The dwObjectID parameter is an HDRVDIALOGINSTANCE, as returned to the service provider when it sent a LINE_CREATEDIALOGINSTANCE message. This is used when the callback is invoked during the processing of TUISPI_providerGenericDialog.
lpParams
Pointer to a memory area used to hold a parameter block.
dwSize
The size in bytes of the parameter block.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_providerGenericDialogData, TUISPIDLL_OBJECT_, TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove, LINE_CREATEDIALOGINSTANCE, TUISPI_providerGenericDialog


TSPI Structures

The data structures TSPI uses are identical to those defined in TAPI Structures, with the exception of TUISPICREATEDIALOGINSTANCEPARAMS.

In the case of most of the larger data structures, the responsibility for filling in members is divided between the service provider and TAPI. The service provider must preserve the values present in members owned by TAPI. The description of which members must be set by the service provider and which must be preserved is provided in the Functions section in the functions that refer to that data structure.

For each structure, the reference section lists the following items:

  • The purpose of the structure
  • A description of the values or fields
  • A description of the structure's extensibility
  • Optional comments about using the structure
  • Optional references to other functions, messages, constants, or structures.

Memory for all data structures whose representation is published and shared by both TAPI and the service provider is allocated by TAPI or an application using TAPI. TAPI passes a pointer to the TSPI function that returns the information. TSPI fills the data structure with the requested information. If the operation is asynchronous, the information is not available until the asynchronous reply callback indicates success.

Note Some structures include Size and Offset fields for defining the location and length of strings in the variable portion of the structure. If the service provider is requested to add a string but no string is available, the service provider must indicate this condition in one of these ways:

  • Set both the Size and Offset fields to 0.
  • Set the Offset field to nonzero but Size to 0.
  • Set the Offset field to nonzero, Size to 1, and the byte at the Offset to 0.


Opaque Handles

A few types defined by TSPI are opaque handles. These are used in TSPI as public references to private data structures. This allows type-checking of parameters supplied to the interface procedures while still giving a measure of type protection. Only the owner of the private data structure knows how to interpret the opaque type as a reference to its data structure representation. As an example of how opaque handles are used, consider a phone device. Both TAPI and the service provider typically maintain data structures representing their respective views of the device.

In typical phone data structures maintained by TAPI and a service provider, each contains an opaque handle for the other data structure. These were exchanged at an early initialization step. When TAPI calls a TSPI function, it passes the opaque handle to refer to the device. The service provider knows how to resolve this as a reference (arrow) to its data structure. A similar process occurs when the service provider calls a callback function in TAPI.


Opaque Handles and Private Data Structures

Opaque handles are used in TSPI to refer to the data structures representing lines, phones, and call appearances. These appear as parameters to most of the functions and callbacks. There are few functions that refer to the device using a device identifier instead of an opaque handle. In such a case, the reference is to the device itself rather than to a data structure. Functions that work in this fashion are typically those called at early initialization times before data structures are created and opaque handles are exchanged.

The service provider must decide how to interpret these handles. A service provider typically uses the pointer to its data structure or to the index into an array of data structures as its opaque handle. The only restriction is that the service provider cannot use the value 0 as an HDRVLINE, HDRVCALL, or HDRVPHONE. The value 0 or NULL for a handle has a special meaning in some operations.


Structure Extensibility

Provisions are made for extending constants and structures both in a device-independent way and in a device-specific (vendor-specific) way.

In constants that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values is identified as device specific. A vendor can define meanings for these values in any way. The interpretation of these values is keyed to the extension identifier provided through the LINEDEVCAPS data structure. For constants that are defined as bit flags, a range of low-order bits are reserved, where the high-order bits can be extension specific. It is recommended that extended values and bit arrays use bits from the highest value or high-order bit down. This leaves the option to move the border between the common portion and extension portion if there is need to do so in the future. Extensions to data structures are assigned a variably sized field with size/offset being part of the fixed part. TSPI describes for each data structure what device-specific extensions are allowed.

In addition to recognizing a specific extension identifier, TAPI (operating on behalf of an application) must negotiate the extension version number that the application and the service provider operate under. This is done using the TSPI_lineNegotiateExtVersion and TSPI_phoneNegotiateExtVersion functions.

An extension identifier is a globally unique identifier. There is no central registry for extension identifiers. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. The number is made up of parts such as a (unique) LAN address, time of day, and random number, to guarantee global uniqueness. Globally unique identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.


TUISPI Data Structures

This section describes the Telephony user interface SPI data structure, which is:

  • TUISPICREATEDIALOGINSTANCEPARAMS


TUISPICREATEDIALOGINSTANCEPARAMS

typedef struct tuispicreatedialoginstanceparams_tag {
  DRV_REQUESTID        dwRequestID;
  HDRVDIALOGINSTANCE   hdDlgInst;
  HTAPIDIALOGINSTANCE  htDlgInst;
  LPCWSTR              lpszUIDLLName;
   LPVOID               lpParams;
   DWORD                dwSize;
} TUISPICREATEDIALOGINSTANCEPARAMS,
  FAR *LP TUISPICREATEDIALOGINSTANCEPARAMS;

Members

dwRequestID
The dwRequestID passed to the service provider as a parameter in the asynchronous TSPI function with which the spontaneous UI is associated. TAPI uses this to identify the application in whose context the UI DLL is to be loaded and the TUISPI_providerGenericDialog function invoked.
hdDlgInst
The service provider's identifier for the association with the instance of the generic dialog box. Because it is possible for multiple instances of the generic dialog box to be open in the same or multiple applications, the service provider must ensure that its handle is unique within the scope of existing instances within the context of the provider.
htDlgInst
TAPI writes into this member its identifier for the association that is created. This member is set to NULL if creating the association failed, in which case it is impossible for the service provider to create a dialog box spontaneously in the context of the target application. The service provider must use this identifier in messages to send data to the UI DLL (LINE_SENDDIALOGINSTANCEDATA).
lpszUIDLLName
Pointer to a NULL-terminated string specifying the fully qualified name of the UI DLL to load in the application context.
lpParams
Pointer to a private parameter block to be conveyed to the UI DLL's TUISPI_providerGenericDialog function. The service provider and UI DLL determine the contents of the parameter block. The transfer is unidirectional; the UI DLL is not able to modify the parameter block and return it to the service provider. Generally, this block instructs the UI DLL which dialog box to display, and contains the information to display (if necessary).
dwSize
The size in bytes of the parameter block.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TUISPI_providerGenericDialog, LINE_SENDDIALOGINSTANCEDATA


TSPI Constants

This section describes the line-device constants defined by the Telephony SPI. Most of the constants used in TSPI programming are the same as those defined in TAPI Constants.


Constant Extensibility

Provisions are made for extending constants and structures both in a device-independent way and in a device-specific (vendor-specific) way.

In constants that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values is identified as device specific. A vendor can define meanings for these values in any way desired. The interpretation of these values is keyed to the extension ID provided through the LINEDEVCAPS data structure. For constants that are defined as bit flags, a range of low-order bits are reserved, where the high-order bits can be extension specific. It is recommended that extended values and bit arrays use bits from the highest value or high-order bit down. This leaves the option to move the border between the common portion and extension portion if needed to do so in the future. Extensions to data structures are assigned a variably sized field with size/offset being part of the fixed part. TSPI describes what device-specific extensions are allowed for each data structure.

In addition to recognizing a specific extension identifier, TAPI (operating on behalf of an application) must negotiate the extension version number that the application and the service provider will operate under. This is done using the TSPI_lineNegotiateExtVersion and TSPI_phoneNegotiateExtVersion functions.

An extension identifier is a globally unique identifier. There is no central registry for extension identifiers. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. To guarantee global uniqueness, the number is composed of parts such as a (unique) LAN address, time of day, and a random number. Globally unique identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.


LINEQOSREQUESTTYPE_ Constants

These constants are used by a TSP to identity the type of a QoS (Quality of Service) request being made. Currently, only a service level request is supported. See LINEQOSSERVICELEVEL_ Constants.

LINEQOSREQUESTTYPE_SERVICELEVEL 0x00000001
The QoS request being made is for a particular service level.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.


LINEQOSSERVICELEVEL_ Constants

These constants are used by a TSP to identity the type of a QoS (Quality of Service) level required.

LINEQOSSERVICELEVEL_NEEDED 0x00000001
The quality of service level requested is a requirement.
LINEQOSSERVICELEVEL_IFAVAILABLE 0x00000002
The quality of service level required, if available.
LINEQOSSERVICELEVEL_BESTEFFORT 0x00000003
The quality of service level required is "best effort."

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.


LINEEQOSINFO_ Constants

These constants are used by a TSP to identity the result of a QoS (Quality of Service) request.

LINEEQOSINFO_NOQOS 0x00000001
QoS is not available.
LINEEQOSINFO_ADMISSIONFAILURE 0x00000002
The QoS request could not be met.
LINEEQOSINFO_POLICYFAILURE 0x00000003
The type of QoS requested is not supported.
LINEEQOSINFO_GENERICERROR 0x00000004
Unspecified QoS error.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.


TUISPIDLL_OBJECT_

TUISPIDLL_OBJECT_LINEID 0x00000001
TUISPIDLL_OBJECT_PHONEID 0x00000002
TUISPIDLL_OBJECT_PROVIDERID 0x00000003
TUISPIDLL_OBJECT_DIALOGINSTANCE 0x00000004

Parameters

TUISPIDLL_OBJECT_LINEID
dwObjectID is a line device identifier (dwDeviceID).
TUISPIDLL_OBJECT_PHONEID
dwObjectID is a phone device identifier (dwDeviceID).
TUISPIDLL_OBJECT_PROVIDERID
dwObjectID is a permanent provider identifier.
TUISPIDLL_OBJECT_DIALOGINSTANCE
dwObjectID is a dialog instance handle (either HDRVDIALOGINSTANCE or HTAPIDIALOGINSTANCE, depending on the context).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.


TSPI Messages

This section contains a list of the messages in the Telephony Service Provider Interface (TSPI). These messages are used to notify TAPI of the occurrence of asynchronous events that spontaneously occur within the service provider. The service provider passes these events to TAPI by calling a LINEEVENT or PHONEEVENT callback function, depending on whether the service provider is reporting an event on a line, call, or phone device. The LINEEVENT procedure for reporting events occurring on a line or call is supplied to the service provider at the time the line is opened with the TSPI_lineOpen function. The PHONEEVENT procedure for reporting events occurring on a phone is supplied with the TSPI_phoneOpen function.

These spontaneous events are unsolicited by TAPI in the sense that they are not a direct response to any request. These events contrast with those reporting completion of requests made by TAPI. Such completion events are reported through the ASYNC_COMPLETION callback function.

The parameter profiles for the spontaneous event procedures include parameters that identify the relevant object for which the event is being reported (phone, line, or call). The identification is in the form of an opaque handle whose exact interpretation is not published by TSPI. TAPI internally determines the relationship between these opaque handles and whatever data structures it used to represent the devices.

The parameter profile for spontaneous event procedures also includes a message parameter identifying the type of the message. Each message type has a corresponding definition that determines the handles that are included, along with other parameters and their meanings. There is a very strong correspondence between the messages appearing at the TSPI level and those that appear at the TAPI level. These are the general rules of correspondence:

  • The set of messages is nearly identical. Where messages correspond, the same message name and value is used at the TSPI level.
  • Handles appearing at the TSPI level are the opaque types defined by the TSPI specification. These types (and their interpretation) differ from those at the TAPI level, although they refer to the same class of device. For example, where a TAPI message includes an HLINE handle, the corresponding TSPI message would typically include an HTAPILINE handle.
  • There is no dwCallbackInstance data passed to the callback.
  • The dwParam1, dwParam2, and dwParam3 parameters are usually identical to the corresponding parameters for the TAPI message.
  • Line-oriented and call-oriented messages are passed to a different callback procedure than phone-oriented messages.

For each message, this section lists the following items:

  • The purpose of the message
  • The callback procedure to which this message is passed
  • A description of the message parameters
  • Optional comments about using the message
  • Optional references to other functions, messages, and data structures
  • Optional comments comparing this message to the TAPI interface

Certain messages are used to notify TAPI about a change in an object's status. These messages provide the TAPI opaque object handle and an indication of which status item has changed. TAPI can subsequently call an appropriate "get status" function of the object to obtain the object's full status.

When an event occurs, a message may or may not be sent to TAPI. For some event types, such as status changes, TAPI specifies a set of status changes in which it is interested. The service provider is advised to limit the status-change message events it reports to those included in this set. The service provider is not required to adhere to this limit. In other words, it may report more changes than are strictly necessary. However, it should try to observe the limit for performance reasons.

The LINE_REPLY message is not used at the TSPI level. Completion of an asynchronous request is reported using the ASYNC_COMPLETION callback.

The PHONE_REPLY message is not used at the TSPI level. Completion of an asynchronous request is reported using the ASYNC_COMPLETION callback.

For more information see the following topics:

  • TSPI Line Device Messages
  • TSPI Phone Device Messages


TSPI Line Device Messages

This section contains the reference for the following TSPI line device messages:

  • LINE_ADDRESSSTATE
  • LINE_CALLDEVSPECIFIC
  • LINE_DEVSPECIFICEX
  • LINE_CALLDEVSPECIFICFEATURE
  • LINE_CALLINFO
  • LINE_CALLSTATE
  • LINE_CLOSE
  • LINE_CREATE
  • LINE_CREATEDIALOGINSTANCE
  • LINE_DEVSPECIFIC
  • LINE_DEVSPECIFICFEATURE
  • LINE_GATHERDIGITS
  • LINE_GENERATE
  • LINE_LINEDEVSTATE
  • LINE_MONITORDIGITS
  • LINE_MONITORMEDIA
  • LINE_MONITORTONE
  • LINE_NEWCALL
  • LINE_REMOVE
  • LINE_SENDDIALOGINSTANCEDATA
  • LINE_SENDMSPDATA
  • LINE_QOSINFO


LINE_ADDRESSSTATE

The TSPI LINE_ADDRESSSTATE message is sent to the LINEEVENT callback function when the status of an address changes on a line that is currently open by TAPI. TAPI can invoke TSPI_lineGetAddressStatus to determine the current status of the address.

LINE_ADDRESSSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_ADDRESSSTATE;
dwParam1 = (DWORD) idAddress;
dwParam2 = (DWORD) AddressState;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_ADDRESSSTATE.
dwParam1
The address identifier of the address that changed status.
dwParam2
The address state that changed. This parameter can be a combination of the LINEADDRESSSTATE_ constants.
dwParam3
Unused.

Remarks

This message is sent whenever the line is open by TAPI and an event occurs in which TAPI has expressed an interest. TAPI uses the TSPI_lineSetStatusMessages function to specify the set of status-change events in which it is interested. By default, address status reporting is disabled.

For backward compatibility, older service providers are not expected to generate this value in a LINE_ADDRESSSTATE message. If they do, the message should be handled in the same manner as for newer service providers (as described earlier).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_LINEDEVSTATE, LINEADDRESSCAPS, LINEADDRESSSTATUS, LINEEVENT, TSPI_lineGetAddressStatus, TSPI_lineSetStatusMessages


LINE_CALLDEVSPECIFIC

The TSPI LINE_CALLDEVSPECIFIC message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a call. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_CALLDEVSPECIFIC
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLDEVSPECIFIC;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLDEVSPECIFIC.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

The LINE_CALLDEVSPECIFIC message is used by a service provider in conjunction with the TSPI_lineDevSpecific function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFIC message to applications in response to receiving this message from a service provider. The htLine and htCall parameters are translated to the appropriate hCall as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

There is no directly corresponding message at the TAPI level, although this message is very similar to LINE_DEVSPECIFIC. At the TSPI level, the device-specific messages are split between those reporting events on lines and addresses, and those reporting events on calls.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_DEVSPECIFIC, LINEEVENT, TSPI_lineDevSpecific


LINE_CALLDEVSPECIFICFEATURE

The TSPI LINE_CALLDEVSPECIFICFEATURE message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a line or address. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_CALLDEVSPECIFICFEATURE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLDEVSPECIFICFEATURE;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLDEVSPECIFICFEATURE.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

This message is used by a service provider in conjunction with the TSPI_lineDevSpecificFeature function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFICFEATURE message to applications in response to receiving this message from a service provider. The htLine and htCall parameters are translated to the appropriate hCall as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

There is no directly corresponding message at the TAPI level, although this message is very similar to LINE_DEVSPECIFICFEATURE. At the TSPI level, the device-specific feature messages are split between those reporting events on lines and addresses, and those reporting events on calls.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_DEVSPECIFICFEATURE, TSPI_lineDevSpecificFeature


LINE_CALLINFO

The TSPI LINE_CALLINFO message is sent to the LINEEVENT callback function when the call information about the specified call has changed. TAPI can invoke lineGetCallInfo to determine the current call information.

LINE_CALLINFO
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLINFO;
dwParam1 = (DWORD) CallInfoState;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLINFO.
dwParam1
Specifies the call information item that has changed. This parameter can be a combination of the LINECALLINFOSTATE_ constants.
dwParam2
Unused.
dwParam3
Unused.

Remarks

This message is sent to TAPI whenever the event occurs and TAPI has the line open. However, no LINE_CALLINFO messages are sent for a call after the call has entered the idle state.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINECALLINFOSTATE_ Constants, TSPI_lineGetCallInfo


LINE_CALLSTATE

The TSPI LINE_CALLSTATE message is sent to the LINEEVENT callback function whenever the status of the specified call has changed. Several such messages are typically sent during the lifetime of a call. The first such message for an incoming call indicates the offering state. TAPI can use TSPI_lineGetCallStatus to find out more detailed information about the current status of the call.

LINE_CALLSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLSTATE;
dwParam1 = (DWORD) LineCallState;
dwParam2 = (DWORD) StateData;
dwParam3 = (DWORD) MediaMode;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLSTATE.
dwParam1
The new call state. This parameter is one of the LINECALLSTATE_ constants.
dwParam2
Specifies call-state-dependent information.

If dwParam1 is LINECALLSTATE_BUSY, the dwParam2 parameter contains the details about the busy mode, and uses the LINEBUSYMODE_ constants.

If dwParam1 is LINECALLSTATE_DIALTONE, the dwParam2 parameter contains the details about the dial tone mode, and uses the LINEDIALTONEMODE_ constants.

If dwParam1 is LINECALLSTATE_SPECIALINFO, the dwParam2 parameter contains the details about the special info mode and uses the LINESPECIALINFO_ constants.

If dwParam1 is LINECALLSTATE_DISCONNECTED, the dwParam2 parameter contains the details about the disconnect mode, and uses the LINEDISCONNECTMODE_ constants.

If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the htCall of the parent call of the conference of which the subject htCall is a member. If the call specified in dwParam2 was not previously considered by TAPI to be a parent conference call, this message causes it to be so treated. The call specified in dwParam2 must already exist; it was most likely previously created by a LINE_NEWCALL message and set to LINECALLSTATE_ONHOLDPENDCONF.

dwParam3
The media type of the call, as far as it is known. This is a combination of one or more LINEMEDIAMODE_ constants. If the service provider does not know the media type, it should include the "UNKNOWN" bit with all media types currently being monitored for.

Remarks

The LINE_CALLSTATE message (with LINECALLSTATE_OFFERING) should be sent as the next message for an incoming call after LINE_NEWCALL. Other call state changes are reported whenever they occur; the message cannot be disabled.

The LINE_CALLSTATE message also notifies TAPI about the existence and state of outbound calls established as a side effect of other calls (for example, when an active call is put on hold and replaced by a new call in the dialtone state) or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which is not offering. By examining the call state, TAPI can determine whether the call is an inbound call that needs to be answered.

The corresponding message at the TAPI level is used to inform applications of new incoming calls. This is not the case at the TSPI level; the LINE_NEWCALL message informs TAPI of new incoming calls. The LINE_NEWCALL message must precede this message.

The dwParam3 parameter is used at the TAPI level to inform the recipient of the privilege level it has over the call.

For backward compatibility, older service providers do not pass a valid htCall in dwParam2. TAPI must check the value passed, and ignore it if it is not a valid htCall. If the value is a valid htCall, TAPI also checks the API version in use on the line device, and establishes a conference call internally only if the API version is 1.4 or later (for example, if the API version on the line is later than 1.4, this parameter should be ignored).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_NEWCALL, LINEBUSYMODE_ Constants, LINECALLSTATE_ Constants, LINECALLSTATUS, LINEDIALTONEMODE_ Constants, LINESPECIALINFO_ Constants, TSPI_lineGetCallStatus


LINE_CLOSE

The TSPI LINE_CLOSE message is sent to the LINEEVENT callback function by the service provider to request that TAPI close the specified line device. Once closed, the line device handle or any call handles for calls on the line are no longer valid. The service provider guarantees that all asynchronous requests on the line and all calls on the line have been reported complete by calling ASYNC_COMPLETION for each outstanding request before this message is sent. TAPI must not request any future operations using this line handle or its associated call handles.

LINE_CLOSE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_CLOSE;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_CLOSE.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Remarks

The LINE_CLOSE message is a request from the service provider to TAPI to close the line. The service provider must not actually close the line until TAPI acknowledges the request by calling the TSPI_lineClose function to direct the service provider to close the line. A service provider can send this message, for example, when taking the line out of service or reconfiguring the service provider. Whether or not the line can be reopened immediately after it is closed is up to the service provider.

A service provider can also request that a line device be closed after the user has modified the configuration of that line or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), a service provider can close the line device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

ASYNC_COMPLETION, TSPI_lineClose


LINE_CREATE

The TSPI LINE_CREATE message is sent to the LINEEVENT callback function when it desires to create a new device. This can occur when a new device is detected by Plug and Play, or dynamically enabled by the user through a provider configuration function. During the LINEEVENT callback procedure, TAPI simply queues this message for later processing. When the message is received from the queue, the TSPI_providerCreateLineDevice function is called in the context of the Tapisrv.exe process.

LINE_CREATE
htLine = (HTAPILINE) 0;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_CREATE;
dwParam1 = (DWORD) hProvider;
dwParam2 = (DWORD) TempDeviceId;
dwParam3 = (DWORD) 0;

Parameters

htLine
Unused.
htCall
Unused.
dwMsg
The value LINE_CREATE.
dwParam1
The service provider handle (hProvider) as received in TSPI_providerEnumDevices.
dwParam2
Contains a temporary device identifier generated by the service provider. TAPI uses this value in a subsequent call to TSPI_providerCreateLineDevice to assist the provider in associating the message and the function call (in the event that multiple devices are being created).
dwParam3
Unused.

Return Values

No return value.

Remarks

Service providers can (and should) continue to make "static" device allocations at startup when TAPI calls TSPI_providerEnumDevices. Creating known devices using this mechanism, instead of always using LINE_CREATE, involves lower overhead for applications (because they don't have to process LINE_CREATE messages, updated device information, and so on). The LINE_CREATE mechanism is intended to be used only if new devices are created while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to the LINEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_lineOpen function; the LINE_CREATE message can be sent to the LINEEVENT callback function given to any open line or at startup.

Devices cannot be removed dynamically. If a service provider wants to remove a line from service, it can send a LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE) message. It would then refuse (for example, by returning LINEERR_INVALLINESTATE) to perform any operation with the device until it returns to service or the provider is shut down and restarted (in which case the device could not be declared in TSPI_providerEnumDevices, effectively removing it from the system).

For backward compatibility, older service providers are not expected to send this message. If they do, the message is treated in the same manner as described earlier for new service providers.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_LINEDEVSTATE, LINEEVENT, TSPI_lineOpen, TSPI_providerCreateLineDevice, TSPI_providerEnumDevices, TSPI_providerInit, TSPI_providerShutdown


LINE_CREATEDIALOGINSTANCE

The TSPI LINE_CREATEDIALOGINSTANCE message causes TAPI to create an association between the service provider and an instance of the TUISPI_providerGenericDialog function executing in the context of the application that invoked the asynchronous TSPI function identified by the dwRequestID parameter of the TUISPICREATEDIALOGINSTANCEPARAMS structure pointed to by lpTUISPICreateDialogInstanceParams.

LINE_CREATEDIALOGINSTANCE
htLine = (DWORD) hProvider;
htCall = (DWORD) 0;
dwMsg = LINE_CREATEDIALOGINSTANCE;
dwParam1 = (DWORD) lpTUISPICreateDialogInstanceParams;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hProvider
The ProviderHandle supplied to the service provider as a parameter to TSPI_providerEnumDevices.
lpTUISPICreateDialogInstanceParams
Pointer to a TUISPICREATEDIALOGINSTANCEPARAMS structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TSPI_providerEnumDevices, TUISPICREATEDIALOGINSTANCEPARAMS


LINE_DEVSPECIFIC

The TSPI LINE_DEVSPECIFIC message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a line or address. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_DEVSPECIFIC
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_DEVSPECIFIC;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_DEVSPECIFIC.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

This message is used by a service provider in conjunction with the TSPI_lineDevSpecific function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFIC message to applications in response to receiving this message from a service provider. The htLine is translated to the appropriate hLine as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

This differs from the corresponding message at the TAPI level in that it is used only to report device-specific events occurring on a line or address. At the TSPI level, the LINE_CALLDEVSPECIFIC message is used to report device-specific events happening on a call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_DEVSPECIFICEX, LINEEVENT, TSPI_lineDevSpecific


LINE_DEVSPECIFICEX

The TSPI LINE_DEVSPECIFICEX message is sent to the LINEEVENT callback function to notify TAPI about extended device-specific events occurring on a line or address. The meaning of the message and the interpretation of the dwParam1, dwParam2, and dwParam3 parameters is device specific.

LINE_DEVSPECIFICEX
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_DEVSPECIFICEX;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_DEVSPECIFICEX.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

This message is used by a service provider in conjunction with the TSPI_lineDevSpecific function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFICEX message to applications in response to receiving this message from a service provider. The htLine parameter is translated to the appropriate hLine as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLDEVSPECIFIC, LINEEVENT, TSPI_lineDevSpecific


LINE_DEVSPECIFICFEATURE

The TSPI LINE_DEVSPECIFICFEATURE message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a line or address. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_DEVSPECIFICFEATURE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_DEVSPECIFICFEATURE;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_DEVSPECIFICFEATURE.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

This message is used by a service provider in conjunction with the TSPI_lineDevSpecificFeature function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFICFEATURE message to applications in response to receiving this message from a service provider. The htLine is translated to the appropriate hLine as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

This differs from the corresponding message at the TAPI level in that it is used only to report device-specific feature events occurring on a line or address. At the TSPI level, the LINE_CALLDEVSPECIFICFEATURE message is used to report device-specific feature events happening on a call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CALLDEVSPECIFICFEATURE, TSPI_lineDevSpecificFeature


LINE_GATHERDIGITS

The TSPI LINE_GATHERDIGITS message is sent to the LINEEVENT callback function when the current buffered digit gathering request has terminated. This message is not sent when digit gathering is canceled. The digit buffer can be examined after this message has been received. The effect of examining the digit buffer before this message has been received is undefined.

LINE_GATHERDIGITS
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_GATHERDIGITS;
dwParam1 = (DWORD) LineGatherTerminate;
dwParam2 = (DWORD) dwEndToEndID;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_GATHERDIGITS.
dwParam1
Specifies the reason why digit gathering was terminated. This parameter can be one of the LINEGATHERTERM_ constants.
dwParam2
The dwEndToEndID that was specified in the original TSPI_lineGatherDigits request for which this is the final result.
dwParam3
Service providers shall insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the digit gathering completed.

Remarks

Calling TSPI_lineGatherDigits while digit gathering is in progress cancels the current digit gathering request and starts a new one, but does not result in the service provider sending this message.

The corresponding message at the TAPI level does not include an end-to-end identifier. End-to-end marking is only done at the TSPI level.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEGATHERTERM_ Constants, TSPI_lineGatherDigits


LINE_GENERATE

The TSPI LINE_GENERATE message is sent to the LINEEVENT callback function to notify TAPI that the current digit or tone generation has terminated. Note that only one such generation request can be in progress on a given call at any time. This message is also sent when digit or tone generation is canceled.

LINE_GENERATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_GENERATE;
dwParam1 = (DWORD) LineGenerateTerminate;
dwParam2 = (DWORD) dwEndToEndID;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_GENERATE.
dwParam1
Specifies the reason why digit or tone generation was terminated, and can be one of the LINEGENERATETERM_ constants.
dwParam2
The dwEndToEndID parameter that was specified in the original TSPI_lineGenerateDigits or TSPI_lineGenerateTone request for which this is the final result.
dwParam3
Service providers insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the digit or tone generation completed.

Remarks

Calling either TSPI_lineGenerateDigits or TSPI_lineGenerateTone while digit or tone generation is in progress cancels the current digit or tone generation request and starts a new request and also results in the service provider sending this message.

The corresponding message at the TAPI level does not include an end-to-end identifier. End-to-end marking is only done at the TSPI level.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEEVENT, LINEGENERATETERM_ Constants, TSPI_lineGenerateDigits, TSPI_lineGenerateTone


LINE_LINEDEVSTATE

The TSPI LINE_LINEDEVSTATE message is sent to the LINEEVENT callback function when the state of a line device has changed. TAPI can invoke TSPI_lineGetLineDevStatus to determine the new status of the line.

LINE_LINEDEVSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_LINEDEVSTATE;
dwParam1 = (DWORD) LineDevState;
dwParam2 = (DWORD) DevStateData1;
dwParam3 = (DWORD) DevStateData2;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_LINEDEVSTATE.

Specifies the callback instance supplied when opening the line.

dwParam1
Specifies the line device status item that has changed. This parameter uses one or more of the LINEDEVSTATE_ constants.
dwParam2
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability.
dwParam3
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.

Remarks

The sending of this message can be controlled through TSPI_lineSetStatusMessages. The service provider must send LINE_LINEDEVSTATE messages for at least the set of status changes selected through that procedure. The service provider can send more than this set, however, it should try to limit its messages to this set for performance reasons. By default all status reporting is disabled.

At the TSPI level, the service provider does not report state changes when the line is opened and closed, since there is only ever one Open outstanding for the device.

For backward compatibility, older service providers would not be expected to generate these values. If they do, TAPI treats them the same as if the service provider were using API version 1.4 or later (as described earlier).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEDEVSTATUS, LINEEVENT, TSPI_lineGetLineDevStatus, TSPI_lineSetStatusMessages


LINE_MONITORDIGITS

The TSPI LINE_MONITORDIGITS message is sent to the LINEEVENT callback function whenever a digit is detected while digit monitoring is in progress. The sending of this message is controlled by the TSPI_lineMonitorDigits function.

LINE_MONITORDIGITS
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_MONITORDIGITS;
dwParam1 = (DWORD) chDigit;
dwParam2 = (DWORD) LineDigitMode;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_MONITORDIGITS.
dwParam1
The low-order byte contains the last digit received in ASCII.
dwParam2
Specifies the digit mode that was detected. This parameter can be one of the LINEDIGITMODE_ constants.
dwParam3
Service providers shall insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the specified digit was detected.

Remarks

This message is sent only when digit monitoring is enabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEEVENT, TSPI_lineMonitorDigits


LINE_MONITORMEDIA

The TSPI LINE_MONITORMEDIA message is sent to the LINEEVENT callback function whenever a change in the call's media type is detected and media type monitoring is enabled. The sending of this message is controlled by the TSPI_lineMonitorMedia function.

LINE_MONITORMEDIA
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_MONITORMEDIA;
dwParam1 = (DWORD) LineMediaMode;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_MONITORMEDIA.
dwParam1
Specifies the new media type (mode). This parameter can be one of the LINEMEDIAMODE_ constants.
dwParam2
Unused.
dwParam3
Service providers insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the specified media was detected.

Remarks

This message is sent only when media type monitoring is enabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEEVENT, LINEMEDIAMODE_ Constants, TSPI_lineMonitorMedia


LINE_MONITORTONE

The TSPI LINE_MONITORTONE message is sent to the LINEEVENT callback function whenever a monitored tone is detected. The sending of this message is controlled by the TSPI_lineMonitorTones function. A single tone detection can result in the service provider sending this message several times in the case where the detected tone matches several tone descriptions in several different tone lists. A tone can "match" several nonidentical tone descriptions, depending on how close they are to one another and the discrimination limits achieved by the service provider. Multiple matches can occur within the same or different tone lists.

LINE_MONITORTONE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_MONITORTONE;
dwParam1 = (DWORD) dwAppSpecific;
dwParam2 = (DWORD) dwToneListID;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_MONITORTONE.
dwParam1
The application-specific member dwAppSpecific of the LINEMONITORTONE structure for the tone that was detected.
dwParam2
The dwToneListID member of the tone list containing a matching tone description.
dwParam3
Service providers insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the tone was detected.

Remarks

This message is sent once for each tone it matches in each tone list. Because there can be multiple matches both within a single tone list and across multiple tone lists, a single tone detection can result in several messages, indicating the same dwToneListID and several messages with a differing dwToneListID.

The dwParam2 parameter in the corresponding message at the TAPI level is unused. TAPI forwards all tone monitoring requests from all applications to the service provider to be handled concurrently. It assigns a unique dwToneListID to each tone list and uses the dwToneListID added to dwParam2 at the TAPI level to discriminate the resulting messages.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINEEVENT, LINEMONITORTONE, TSPI_lineMonitorTones


LINE_NEWCALL

The TSPI LINE_NEWCALL message is sent to the LINEEVENT callback function whenever a new call that TAPI has not originated arrives on a line that TAPI has open. This must be the first message sent regarding that call. TAPI writes the htCall opaque handle to the location passed by the service provider as dwParam2. This gives the service provider the htCall value to be used in subsequent messages.

LINE_NEWCALL
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_NEWCALL;
dwParam1 = (DWORD)(HDRVCALL) hdCall;
dwParam2 = (DWORD)(LPHTAPICALL) &htCall;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_NEWCALL.
dwParam1
The service provider's opaque handle for the call, of type HDRVCALL. TAPI passes this value as the hdCall parameter to identify the call in subsequent procedures it invokes to operate on the call.
dwParam2
A pointer of type LPHTAPICALL pointing to a HTAPICALL. TAPI writes the TAPI opaque handle for the call to the indicated location. The service provider must save this value and pass it as the htCall parameter to identify the call in subsequent events it reports for the call.

This parameter can also acquire a value of NULL (see the following Remarks section).

dwParam3
Unused.

Remarks

The service provider should send the LINE_CALLSTATE message as the next message for this call. The LINE_NEWCALL event is unusual in that it also passes a value back to the service provider.

This function reports any new calls that originate in the service provider (inbound, outbound, initiated at the phone, and so on) for which TAPI and the service provider have not yet exchanged opaque handles. The handles are exchanged so that TAPI and the service provider can subsequently make requests and report events involving the call. Because these new calls are not necessarily inbound, the calls can initially be in any state, not necessarily the offering state. If the service provider starts and discovers that one or more calls are already active on the line, it informs TAPI of them with LINE_NEWCALL messages followed by LINE_CALLSTATE messages indicating the current state. A new outgoing call, initiated on the phone by the user, would be reported with a LINE_NEWCALL message, and the initial LINE_CALLSTATE message would indicate that the call was in DIALTONE state (and then continuing on from there).

If the service provider passes a large number of calls to TAPI in a very short amount of time (during the same interrupt cycle), TAPI can become backlogged in processing those calls. When this happens, TAPI signals to the service provider to wait a short time before sending any more calls. It signals this by writing a value of NULL, instead of a valid HTAPICALL, into the location pointed to by the dwParam2 parameter of LINE_NEWCALL. This indicates that the attempt to process the newly offered call handle was not successful, most likely due to a temporary inability to allocate memory. The service provider can respond by dropping the call or by resending the LINE_NEWCALL message after a scheduling delay (during which time the service provider should yield the processor to allow TAPI to process other pending actions). In any case, no further messages regarding the new call can be passed to TAPI until the handle exchange succeeds. When the location pointed to by dwParam2 acquires a non-NULL value, the service provider knows that this value is a valid HTAPICALL handle to the call.

There is no directly corresponding message at the TAPI level. This message is used at the TSPI level to uniquely and unambiguously introduce a new incoming call to TAPI and retrieve the TAPI opaque identifier for the call.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

LINE_CALLSTATE, LINEEVENT


LINE_REMOVE

The TSPI LINE_REMOVE message notifies TAPI that an existing line device has been or is about to be removed from the system.

LINE_REMOVE
htLine = (DWORD) 0;
htCall = (DWORD) 0;
dwMsg = LINE_REMOVE;
dwParam1 = (DWORD) dwDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDeviceID
The device that has been removed.

Remarks

A service provider sends a LINE_REMOVE message to TAPI when it desires to disable an existing line device. This can occur when the removal of the device from the system (in a permanent way) is detected by Plug and Play or through a control panel or other user interface. It should not be used when a device is temporarily disconnected, such as if the device is a PCMCIA card that is extracted (use LINEDEVSTATE_DISCONNECTED or _OUTOFSERVICE in this situation).

When the message is received, TAPI closes the line device (if it is not already closed) by calling TSPI_lineClose, and sends LINE_CLOSE to all applications that have the line open; if any calls are active, TSPI_lineCloseCall is called on each of them prior to TSPI_lineClose. After processing the message, TAPI does not call the service provider referencing the removed device's dwDeviceID. TAPI returns LINEERR_NODEVICE to any application that attempts to reference the removed dwDeviceID.

After TSPI_providerShutdown has been called, the service provider can renumber its devices to remove any numbering "gaps" left by the device removal, so that when TSPI_providerEnumDevices is subsequently called, installed devices are contiguously numbered. The service provider should not reuse the dwPermanentLineID that had been assigned to the device, for as long as possible.

The LINE_REMOVE mechanism is intended to be used only if devices are removed while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to TAPI's LINEEVENT callback entry point. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_lineOpen function; the LINE_REMOVE message can be sent to the LINEEVENT callback function given to any open line or at startup.

Backward Compatibility

Older service providers are not expected to send this message. If they do, the message is treated in the same manner as described earlier for new service providers.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

LINE_CLOSE, TSPI_lineClose, TSPI_lineCloseCall, TSPI_lineOpen, TSPI_providerEnumDevices, TSPI_providerInit, TSPI_providerShutdown


LINE_SENDDIALOGINSTANCEDATA

The TSPI LINE_SENDDIALOGINSTANCEDATA message causes TAPI to call the TUISPI_providerGenericDialogData function in the UI DLL associated with htDlgInst, passing it the parameter block pointed to by lpParams, of length dwSize.

LINE_SENDDIALOGINSTANCEDATA
htLine = (DWORD) htDlgInst;
htCall = (DWORD) 0;
dwMsg = LINE_SENDDIALOGINSTANCEDATA;
dwParam1 = (DWORD) lpParams;
dwParam2 = (DWORD) dwSize;
dwParam3 = (DWORD) 0;

Parameters

htDlgInst
The HTAPIDIALOGINSTANCE that was returned to the service provider when the dialog box instance was created using LINE_CREATEDIALOGINSTANCE.
lpParams
Pointer to a provider-specific parameter block that is conveyed to the UI DLL TUISPI_providerGenericDialogData function, the size of which is specified by dwSize. If this parameter is set to NULL, this is a request to close the dialog box immediately and clean up (the UI DLL should not invoke TUISPIDLLCALLBACK during this cleanup).
dwSize
The size in bytes of the parameter block to be conveyed to the UI DLL.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tspi.h.

See Also

TUISPIDLLCALLBACK, TUISPI_providerGenericDialogData, LINE_CREATEDIALOGINSTANCE


LINE_SENDMSPDATA

The TSPI LINE_SENDMSPDATA message is sent when the telephony service provider (TSP) wants to pass information to the media service provider (MSP).

LINE_SENDMSPDATA
htLine = LineDevice;
htCall = Call;
dwMsg = LINE_SENDMSPDATA;
dwParam1 = (DWORD) htMSPHandle;
dwParam2 = (DWORD) pBuffer;
dwParam3 = (DWORD) dwSize;

Parameters

htLine
The TAPI handle for the line.
htCall
The TAPI handle for the call.
dwMsg
The value LINE_SENDMSPDATA.
dwParam1
Identifies the MSP that should receive the message. If 0, the message will be sent to all MSPs. This is the handle that is passed to the TSPI_LineCreateMSPInstance function.
dwParam2
The buffer to pass to the MSP. The buffer is not interpreted by TAPI.
dwParam3
The size, in bytes, of the buffer in dwParam2.

Remarks

The service provider must negotiate a TAPI version 3.0 or later for this message to operate.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

About The Media Service Provider (MSP), TSPI_lineMSPIdentify, TSPI_lineCreateMSPInstance, TSPI_lineCloseMSPInstance, TSPI_lineRecieveMSPData, LINEDEVCAPS


LINE_QOSINFO

The TSPI LINE_QOSINFO message causes TAPI to fire a QOS event. See ITQOSEvent for additional information.

LINE_QOSINFO
htLine = (DWORD) LineDevice;
htCall = (DWORD) Call;
dwMsg = LINE_QOSINFO;
dwParam1 = (DWORD) QOSEvent;
dwParam2 = (DWORD) MediaMode;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI handle for the line.
htCall
The TAPI handle for the call.
dwMsg
The value LINE_QOSINFO.
dwParam1
A member of the QOS_EVENT enumerator that identifies the type of event.
dwParam2
A media type constant that identifies the media of the call associated with this event.
dwParam3
Unused.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tspi.h.

See Also

QOS_EVENT, ITQOSEvent


TSPI Phone Device Messages

This section contains the reference for the following TSPI phone device messages:

  • PHONE_BUTTON
  • PHONE_CLOSE
  • PHONE_CREATE
  • PHONE_DEVSPECIFIC
  • PHONE_REMOVE
  • PHONE_STATE


PHONE_BUTTON

The TSPI PHONE_BUTTON message is sent to the PHONEEVENT callback function to notify TAPI that it has detected a button press on a phone device that TAPI has open and for which button press monitoring is enabled.

PHONE_BUTTON
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_BUTTON;
dwParam1 = (DWORD) idButtonLamp;
dwParam2 = (DWORD) PhoneButtonMode;
dwParam3 = (DWORD) PhoneButtonState;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_BUTTON.
dwParam1
The button/lamp identifier of the button that was pressed. Note that the button identifiers 0 through 11 are always the KEYPAD buttons. '0' is button identifier 0, '1' is button identifier 1, and so on, through button identifier 9. '*' is button identifier 10, and '#' is button identifier 11. Additional information about a button identifier is available through TSPI_phoneGetDevCaps and TSPI_phoneGetButtonInfo.
dwParam2
The button mode of the button. This parameter uses the PHONEBUTTONMODE_ constants.
dwParam3
Specifies whether this is a button down event or a button up event. This parameter uses one of the PHONEBUTTONSTATE_ constants

Remarks

The set of phone button events that is reported is selected by the TSPI_phoneSetStatusMessages function. The service provider must send PHONE_BUTTON messages for at least the set of button press events selected through that procedure. The service provider can send more than this set but should limit its messages to this set for performance reasons.

A PHONE_BUTTON message is sent whenever a button changes state. The service provider must guarantee that each button DOWN event is strictly paired with a button UP event, in that order. Note that a service provider that can detect only one of the button press or release events should expand the event it does detect into a button DOWN message followed by a button UP message.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONEBUTTONFUNCTION_ Constants, PHONEBUTTONMODE_ Constants, PHONEBUTTONSTATE_ Constants, PHONEEVENT, PHONESTATUS, TSPI_phoneGetButtonInfo, TSPI_phoneGetDevCaps, TSPI_phoneSetStatusMessages,


PHONE_CLOSE

The TSPI PHONE_CLOSE message is sent to the PHONEEVENT callback function when an open phone device has been forcibly closed. The phone device handle is no longer valid once this message has been sent. The service provider guarantees that all asynchronous requests on the phone have been reported complete by calling ASYNC_COMPLETION for each outstanding request before this message is sent. TAPI must not request any future operations using this phone handle.

PHONE_CLOSE
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_CLOSE;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_CLOSE.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Remarks

This message is only sent to TAPI after an open phone has been forcibly closed. This can be done, for example, when taking the phone out of service or reconfiguring the service provider. Whether or not the phone can be reopened immediately after a forced close is up to the service provider.

An open phone device can be forcibly closed after the user has modified the configuration of that phone or its driver. If the user wants the configuration changes to be effective immediately (instead of after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), a service provider can forcibly close the phone device.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

ASYNC_COMPLETION, PHONEEVENT, TSPI_phoneClose


PHONE_CREATE

The TSPI PHONE_CREATE message is sent to the PHONEEVENT callback function to create a new device. This can occur when a new device is detected by Plug and Play, or when a new device is dynamically enabled by the user through a provider configuration function. During the PHONEEVENT callback procedure, TAPI simply queues this message for later processing. When the message is received from the queue, the TSPI_providerCreatePhoneDevice function is called in the context of the Tapisrv.exe process.

PHONE_CREATE
htPhone = (HTAPIPHONE) 0;
dwMsg = (DWORD) PHONE_CREATE;
dwParam1 = (DWORD) hProvider;
dwParam2 = (DWORD) TempDeviceId;
dwParam3 = (DWORD) 0;

Parameters

htPhone
Unused.
dwMsg
The value PHONE_CREATE.
dwParam1
The service provider handle (hProvider) as received in TSPI_providerEnumDevices.
dwParam2
Contains a temporary device identifier generated by the service provider. TAPI uses this value in a subsequent call to TSPI_providerCreatePhoneDevice to assist the provider in associating the message and the function call (in the event that multiple devices are being created).
dwParam3
Unused.

Return Values

No return value.

Remarks

Service providers can (and should) continue to make static device allocations at startup when TAPI calls TSPI_providerEnumDevices. Creating known devices using this mechanism, instead of always using PHONE_CREATE, involves lower overhead for applications (because they don't have to process PHONE_CREATE messages, updated device information, and so on). The PHONE_CREATE mechanism is intended to be used only if new devices are created while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to the PHONEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_phoneOpen function; the PHONE_CREATE message can be sent to the PHONEEVENT callback function given to any open phone or at startup.

Devices cannot be removed dynamically. If a service provider wants to remove a phone from service, it sends a PHONE_STATE (PHONESTATE_DISCONNECTED) message. It can then refuse (for example, by returning PHONEERR_INVALPHONESTATE) to perform any operation with the device until it returns to service or the provider is shut down and restarted (in which case the device could be not declared in TSPI_providerEnumDevices, effectively removing it from the system).

For backward compatibility, older service providers are not expected to send this message. If they do, the message is treated in the same manner as described above for new service providers.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONEEVENT, TSPI_phoneOpen, TSPI_providerCreatePhoneDevice, TSPI_providerEnumDevices, TSPI_providerInit, TSPI_providerShutdown


PHONE_DEVSPECIFIC

The TSPI PHONE_DEVSPECIFIC message is sent to the PHONEEVENT callback function to notify TAPI about device-specific events occurring at the phone. The meaning of the message and the interpretation of the parameters is implementation defined.

PHONE_DEVSPECIFIC
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_DEVSPECIFIC;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_DEVSPECIFIC.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

TAPI sends the PHONE_DEVSPECIFIC message to applications in response to receiving this message from a service provider. The htPhone is translated to the appropriate hPhone as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONEEVENT, TSPI_phoneDevSpecific


PHONE_REMOVE

The TSPI PHONE_REMOVE message notifies TAPI that a phone device has been or is about to be removed from the system.

PHONE_REMOVE
htPhone = (DWORD) 0;
dwMsg = PHONE_REMOVE;
dwParam1 = (DWORD) dwDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDeviceID
The device that has been removed.

Remarks

A service provider sends a PHONE_REMOVE message to TAPI to disable an existing phone device. This can occur when the removal of the device from the system (in a permanent way) is detected by Plug and Play or through a control panel or other user interface. It should not be used when a device is temporarily disconnected, such as if the device is a PCMCIA card that is extracted (use PHONESTATE_DISCONNECTED in this situation).

When the message is received, TAPI closes the phone device (if it is not already closed) by calling TSPI_phoneClose, and sends PHONE_CLOSE to all applications that have the phone open. After processing the message, TAPI does not call the service provider referencing the removed device's dwDeviceID. TAPI returns PHONEERR_NODEVICE to any application that attempts to reference the removed dwDeviceID.

After TSPI_providerShutdown has been called, the service provider can renumber its devices to remove any numbering "gaps" left by the device removal, so that when TSPI_providerEnumDevices is subsequently called, installed devices are contiguously numbered. The service provider should not reuse the dwPermanentPhoneID that had been assigned to the device, for as long as possible.

The PHONE_REMOVE mechanism is to be used only if devices are removed while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to the PHONEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_phoneOpen function; the PHONE_REMOVE message can be sent to the PHONEEVENT callback function given to any open phone or at startup.

Backward Compatibility

Older service providers are not expected to send this message. If they do, the message is treated in the same manner as described above for new service providers.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONE_CLOSE, PHONEEVENT, TSPI_phoneClose, TSPI_phoneOpen, TSPI_providerInit, TSPI_providerShutdown


PHONE_STATE

The TSPI PHONE_STATE message is sent to the PHONEEVENT callback function to TAPI whenever a phone device's status changes.

PHONE_STATE
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_STATE;
dwParam1 = (DWORD) PhoneState;
dwParam2 = (DWORD) PhoneStateData;
dwParam3 = (DWORD) 0;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_STATE.
dwParam1
The phone state that has changed. This parameter uses the PHONESTATE_ constants.
dwParam2
Phone-state dependent information detailing the status change. This parameter is not used if multiple flags are set in dwParam1, because multiple status items have changed. TAPI should invoke TSPI_phoneGetStatus to obtain a complete set of information. If dwParam1 is PHONESTATE_LAMP, dwParam2 contains the button/lamp identifier of the lamp that has changed. If dwParam1 is PHONESTATE_RINGMODE, dwParam2 contains the new ring mode. If dwParam1 is PHONESTATE_HANDSETHOOKSWITCH, PHONESTATE_SPEAKERHOOKSWITCH or PHONESTATE_HEADSETHOOKSWITCH, dwParam2 contains the new hookswitch mode of that hookswitch device, which can be set to any of the PHONEHOOKSWITCHMODE_ constants.
dwParam3
Unused.

Remarks

The sending of this message is controlled by TSPI_phoneSetStatusMessages. By default, this message is disabled for all state changes.

The service provider never reports changed values for PHONESTATE_OWNER or PHONESTATE_MONITORS, because the notion of privilege does not appear at the TSPI level.

For backward compatibility, older service providers are not expected to generate this value in a PHONE_STATE message. If they do, the message is handled in the same manner as for newer service providers (as described earlier).

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP3 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires TAPI 2.0 or later.
Header: Declared in Tapi.h.

See Also

PHONEEVENT, PHONEHOOKSWITCHMODE_ Constants, PHONESTATE_ Constants, TSPI_phoneGetStatus, TSPI_phoneSetStatusMessages


TSPI Device Classes

A device class is a group of related physical devices or device drivers through which applications send and receive the information or data that makes up a call. Every device class has a device class name that uniquely identifies the class and provides information about the programming interface and commands that can be used to open and communicate with the devices in the class.

The Telephony Application Programming Interface (TAPI) associates devices from one or more device classes to each line or phone device. You access one of these devices by retrieving the device identifier for the device using the lineGetID or phoneGetID function. You supply the device class name, and the function returns the specific port name, device name, device handle, or device identifier that you need to open and access the device. The format of the returned information depends on the device class and is described in this section.

Note The device identifier definitions apply to 16-bit and 32-bit TAPI. In some cases, the datatype of a media handle in the device identifier definition may be different from that specified by the Microsoft® Windows® version 3.x or Microsoft® Win32® application programming interface (API). For example, Windows 3.x and Win32 define wave device identifiers with the UINT type, but TAPI defines this device identifier with the DWORD type. In such cases, you cast the media handle to the appropriate datatype when using it with the Windows version 3.x or Win32 API.

You also use device class names with the lineConfigDialog and phoneConfigDialog functions to enable the user to set configuration options for the given device; with the lineGetIcon and phoneGetIcon functions to retrieve an icon to represent the given device; and with the lineGetDevConfig and lineSetDevConfig functions to directly retrieve and set configuration options for the given device.

Following are the default device class names.

Device class name | Description
comm | Communications port
comm/datamodem | Modem through a communications port
comm/datamodem/portname | Name of the device to which a modem is connected
wave/in | Wave audio device (input only)
wave/out | Wave audio device (output only)
wave/in/out | Wave audio device, full duplex
midi/in | MIDI sequencer (input only)
midi/out | MIDI sequencer (output only)
tapi/line | Line device
tapi/phone | Phone device
ndis | Network device
tapi/terminal | Terminal device

These names are not case sensitive, so you can use any combination of uppercase and lowercase letters.

Additional device classes and device class names may be available on a given system. In general, if a device does not belong to one of the default device classes, the manufacturer typically defines a new device class and assigns a unique device class name. You must check the documentation for the device to determine what additional device classes are available for it. Note, however, that although the device class and media type are related, they are not the same. A media type describes a format of information on a call, and a device class defines the programming interface used to manage that information. So, even if a manufacturer defines a new media type, it may not be true that the manufacturer must also define a new device class to support the mode.

The format of the configuration data used with the lineSetDevConfig and lineGetDevConfig functions also depends on the device class. In general, you use lineGetDevConfig to save a copy of the current device configuration data and then later use lineSetDevConfig with the saved configuration data to restore the device configuration to the previous state. This is a convenient way to temporarily change the configuration without requiring the user to manually restore it to the previous state. Because the exact format of the device configuration data may be different with each service provider, do not use lineSetDevConfig and lineGetDevConfig to manipulate the device configuration data directly. Some formats are provided for information only.


comm

The comm device class consists of communications ports. You access these devices using the Win32 file and communications functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_ASCII value and appending a NULL-terminated string that specifies the name of the communication device (such as the modem name).


comm/datamodem

The comm/datamodem device class consists of data modem devices. You access these devices using the Win32 file and communications functions. Devices in this class are associated with line devices that support the LINEMEDIAMODE_DATAMODEM media type, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID function fills a VARSTRING structure, setting dwStringFormat to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE hComm;            // Win32 file handle to data modem
CHAR   szDeviceName[1];  // name of data modem

The hComm member is the handle of the open communications port. This member is NULL if the port is not yet open or if the dwSelect parameter of lineGetID is not the LINECALLSELECT_CALL value. The service provider is responsible for duplicating the handle into the calling process's context, as specified by the hTargetProcess parameter. If a call is active, the service provider typically opens the port itself to get direct control of the communications hardware, but is only required to return a valid handle if the line is connected. The service provider opens the port using the FILE_FLAG_OVERLAPPED value, and then configures the port using the settings specified by the lineSetDevConfig function. An application can set additional configuration options for the device using Win32 functions with the returned handle.

The szDeviceName member is a NULL-terminated string that specifies the name of the communications port associated with the line, address, or call.

When using the lineGetDevConfig and lineSetDevConfig functions, some service providers require that the configuration data for this device class have the following format:

typedef struct  tagDEVCFG  {
    DEVCFGHDR   dfgHdr;
    COMMCONFIG  commconfig;
} DEVCFG, *PDEVCFG, FAR* LPDEVCFG;

// Device setting information
typedef struct  tagDEVCFGDR  {
    DWORD       dwSize;
    DWORD       dwVersion;
    WORD        fwOptions;
    WORD        wWaitBong;
} DEVCFGHDR;

Contains device configuration information for use with the TSPI_lineGetDevConfig and TSPI_lineSetDevConfig functions.

DwSize
Sum of the size of the DEVCFGHDR structure and the actual size of COMMCONFIG structure.
DwVersion
Version number of the Unimodem DevConfig structure. This member can be MDMCFG_VERSION (0x00010003).
FwOptions
Option flags that appear on the Unimodem Option page. This member can be a combination of these values:
TERMINAL_PRE (1)
Displays the preterminal screen.
TERMINAL_POST (2)
Displays the post terminal screen.
MANUAL_DIAL (4)
Dials the phone manually, if capable of doing so.
LAUNCH_LIGHTS (8)
Displays the modem icon in the status area of the taskbar.

Only the LAUNCH_LIGHTS value is set by default.

WWaitBong
Number of seconds (in two seconds granularity) to replace the wait for credit tone ($).
Commconfig
COMMCONFIG structure that can be used with the Win32 communications and MCX functions.


comm/datamodem/portname

The comm/datamodem/portname device class consists of the device names to which modems are attached. When this device name is specified in a call to the TSPI_lineGetID function, the service provider fills the VARSTRING structure with a NULL-terminated ANSI (not Unicode) string specifying the name of the port to which the specified modem is attached, such as "COM1\0". This is intended primarily for identification purposes in the user interface, but could be used under some circumstances to open the device directly, bypassing the service provider (if the service provider does not already have the device open itself). If there is no port associated with the device, a NULL string ("\0") is returned in the VARSTRING structure (with a string length of 1).


wave/in

The wave/in device class consists of audio devices for low-level wave audio input. You access these devices using the wave functions, which are described in the Microsoft Platform Software Development Kit. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media type, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveInOpen function to open the device for input. You can use the resulting device handle to record digitized audio data from the line or phone device.

Although a wave device class also exists for low-level wave audio devices, you should always use the wave/in device class for low-level wave input.


wave/out

The wave/out device class consists of audio devices for low-level wave audio output. You access these devices by using the wave functions, which are described in the Microsoft Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media type, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveOutOpen function to open the device for output. You can use the resulting device handle to play digitized audio data at the line or phone device.

Although a wave device class also exists for low-level wave audio devices, you should always use the wave/out device class for low-level wave output.


wave/in/out

The wave/in/out device class consists of full duplex audio devices. You access these devices by using the wave functions, which are described in the Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media type, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending two additional members:

DWORD DeviceInId;  // identifier of wave in audio device
DWORD DeviceOutId;  // identifier of wave out audio device

The DeviceInId and DeviceOutId members are identifiers of a closed audio device. You use these identifiers in a call to the waveOutOpen function to open the device for output. You can use the resulting device handle to play digitized audio data at the line or phone device.


midi/in

The midi/in device class consists of MIDI sequencers that are used for input. You access these devices using the MIDI functions, which are described in the Microsoft Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiInOpen function to open the device for input. You can use the resulting device handle to record MIDI data from the line or phone device.


midi/out

The midi/out device class consists of MIDI sequencers that are used for output. You access these devices by using the MIDI functions, which are described in the Microsoft Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiOutOpen function to open the device for output. You can use the resulting device handle to play MIDI data at the line or phone device.


tapi/line

The tapi/line device class consists of all line devices. You access these devices using the TAPI line functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD dwDeviceI;  // line device identifier

The dwDeviceId member is the identifier of the line device associated with the line handle given by lineGetID.

The phoneGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

    DWORD adwDeviceIds[];  // array of line device identifiers

The adwDeviceIds member is an array containing the device identifiers of all line devices that are associated with the phone device. If there are no associated line devices, phoneGetID returns the PHONEERR_INVALDEVICECLASS value.


tapi/phone

The tapi/phone device class consists of all phone devices. You access these devices using the TAPI phone functions.

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD dwDeviceI;  // phone device identifier

The dwDeviceId member is the identifier of the phone device associated with the phone handle given by phoneGetID.

The lineGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

    DWORD adwDeviceIds[];  // array of phone device identifiers

The adwDeviceIds member is an array containing the device identifiers of all phone devices that are associated with the given line device. If there are no associated phone devices, lineGetID returns the LINEERR_INVALDEVICECLASS value.


ndis

The ndis device class consists of devices that can be associated with network driver interface specification (NDIS) media access control (MAC) drivers to support network communications. You access these devices by using functions.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending these additional members:

    HANDLE  hDevice;          // NDIS connection identifier
    CHAR    szDeviceType[1];  // name of device

The hDevice member is the identifier to pass to a MAC, such as the asynchronous MAC for dial-up networking, to associate a network connection with the call/modem connection. The szDeviceType member is a NULL-terminated string specifying the name of the device associated with the identifier. For more information, refer to documentation about writing NDIS MAC drivers for use with dial-up networking.


tapi/terminal

The tapi/terminal device class consists of the phone devices associated with each terminal on a line or the terminal on each line associated with a phone device. You access these devices by using the TAPI line or phone functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD adwDeviceId[];  // array of phone device identifiers

The adwDeviceId member is an array of phone device identifiers. There is one array element for each terminal specified by the dwNumTerminals member in the LINEDEVCAPS structure for the given line device. Each element specifies the identifier of the phone device associated with the corresponding terminal on the line. If there is no phone device associated with a terminal, the element is set to –1 (0xFFFFFFFF).

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

    DWORD adwTerminalID[];  // array of terminal identifiers

The adwTerminalID member is an array of terminal identifiers. There is one array element for each line device identifier specified by the lineInitialize function. Each array element contains the terminal identifier associated with the phone device for the given line device. If there is no phone device, the element is set to –1 (0xFFFFFFFF). The terminal identifiers range in value from zero to one less than the number specified by the dwNumTerminals member in the LINEDEVCAPS structure.


TSPI Service Provider Datatypes

This section contains a reference for the following TSPI service provider datatypes:

  • DRV_REQUESTID
  • HDRVCALL
  • HDRVLINE
  • HDRVPHONE
  • HTAPICALL
  • HTAPILINE
  • HTAPIPHONE
  • INITIALIZE_NEGOTIATION
  • TSPIMessage


DRV_REQUESTID

The DRV_REQUESTID datatype is used to supply a unique identifier for a request to the service provider. A value of this type is passed as a parameter to every function that allows for asynchronous operation. If the operation is asynchronous, the service provider returns this value as the return value of the function. Whenever the service provider flags a request as asynchronous in this way, it must eventually report the operation is complete by calling the ASYNC_COMPLETION callback function.

TAPI ensures that the DRV_REQUESTID values it supplies are strictly positive, that is, between the values of 0x00000001 and 0x7FFFFFFF, inclusive. Furthermore, the values are unique in that no value returned from a function to flag the request as asynchronous will be re-used before the operation is reported complete.


HDRVCALL

The HDRVCALL datatype represents a service provider's opaque handle for a call data structure. The service provider must resolve a value of this type into a reference to the appropriate data structure instance.


HDRVLINE

The HDRVLINE datatype represents a service provider's opaque handle for a line data structure. The service provider must resolve a value of this type into a reference to the appropriate data structure instance.


HDRVPHONE

The HDRVPHONE datatype represents a service provider's opaque handle for a phone data structure. The service provider must resolve a value of this type into a reference to the appropriate data structure instance.


HTAPICALL

The HTAPICALL datatype represents the TAPI opaque handle for a call data structure. TAPI must resolve a value of this type into a reference to the appropriate data structure instance. The service provider must not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to TAPI at appropriate times.


HTAPILINE

The HTAPILINE datatype represents the TAPI opaque handle for a line data structure. TAPI must resolve a value of this type into a reference to the appropriate data structure instance. The service provider must not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to TAPI at appropriate times.


HTAPIPHONE

The HTAPIPHONE datatype represents TAPI's opaque handle for a phone data structure. TAPI must resolve a value of this type into a reference to the appropriate data structure instance. The service provider must not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to TAPI at appropriate times.


INITIALIZE_NEGOTIATION

The INITIALIZE_NEGOTIATION datatype is a special value of type DWORD. It can be passed as the dwDeviceID parameter in the TSPI_lineNegotiateTSPIVersion and TSPI_phoneNegotiateTSPIVersion functions. Doing so indicates that TAPI can negotiate a TSPI interface version number independent of any specific devices.


TSPIMessage

TSPIMessage is an enumeration type that defines the set of additional LINEEVENT and PHONEEVENT functions appearing in TSPI that do not appear in TAPI.

Parameters

TSPI_MESSAGE_BASE
The lowest number in the range of TSPI-specific message values. This value has no meaning by itself, but serves as a base for defining the other values.
LINE_NEWCALL
Specifies that a new, incoming call has arrived and introduces it to TAPI. This must be the first message sent to TAPI for a new incoming call. TAPI returns its opaque identifier for the call as part of its handling of this message.
LINE_CALLDEVSPECIFIC
Specifies that a device-specific event has occurred on a call device.
LINE_CALLDEVSPECIFICFEATURE
Specifies that a device-specific feature event has occurred on a call device.


About the Media Service Provider (MSP)

A TAPI 3.0 media service provider (MSP) allows an application considerable control over the media for a particular transport mechanism. An MSP always exists paired with a Telephony Service Provider (TSP). Just as a TSP is an abstraction layer for call control, the MSP controls media without need for device-specific coding. For an example of MSP/TSP communication, see TAPI Service Provider Overview.

An MSP enables media control through the use of special terminal, stream, and substream interfaces defined by TAPI. The diagram in About Call and Media Controls illustrates how these interfaces appear to a TAPI 3 application.

In addition, an MSP may implement private provider-specific interfaces, which TAPI will aggregate onto the standard objects exposed to an application. For example, the Microsoft® IPConf MSP, which is installed with Microsoft Windows® 2000, implements the ITParticipant interface, which provides controls for individual members of a conference.

The following topic briefly describes the MSPs that may be installed with a Microsoft operating system. For details on configuration and usage, see the resource kit for the target platform.

Additional third-party media service providers can be written for particular protocols or for physical devices. The Media Service Provider Interface (MSPI) describes the interfaces that must be implemented to allow an MSP to interact with the components of Microsoft Telephony.


MSP Architecture

In TAPI architecture, all TSPs are run in the context of Tapisrv.exe, which is implemented as a service process within SVCHOST. TAPI applications live in their own process. TAPI applications load Tapi3.dll and any needed MSPs into their own process, and the TAPI DLL communicates with Tapisrv.exe through a private RPC interface. The following diagram illustrates the interaction of these components.

A media service provider (MSP) provides media streaming using the abstractions of Terminals, Streams, and SubStreams.

A Terminal is a sink or source for a media stream. It may be a physical object, such as a speaker or a microphone, or it may be an abstraction of a device, such as a video window. The Terminal Object exposes the ITTerminal interface. The class of terminal is described by the Terminal Class GUID. An MSP may define its own terminal classes.

Streams divide the media of a call based on the media type or type, the stream's direction, and the destination address of the media. For example, an incoming audio stream from a modem is a stream object, an outgoing video stream to an IP address and port is a stream object, the video streams coming from a IP multicast group are also considered as one stream object. The Stream object is represented by the ITStreamControl interface.

SubStreams allow finer control over the media. For example, in the IP multicast case, the incoming video stream object might represent several people. The application will most likely want each participant to have a separate renderer. The incoming video stream can be divided into several substreams, one for each person. One substream would correspond to one person, and can be configured and controlled separately. The SubStream object is represented by the ITSubStreamControl interface.

When an application calls ITAddress::CreateCall to set up a call, it must specify the type of media required. On an outgoing call, it simply tells TAPI when the call is created. For example:

pAddress->CreateCall(
  pszDestAddress,
  lAddressType,
  TAPIMEDIATYPE_AUDIO | TAPIMEDIATYPE_VIDEO,
  &pCall
);

In this case, the application is creating an outgoing audio-video call.

The media types passed in indicate the media that the application is interested in over the lifetime of the call. For example, the application may specify audio and video when creating the call, but select only audio terminals at the beginning. The MSP will start streaming only audio, but will not reject a local or remote video request made later in the lifetime of the call.

When the application then calls ITBasicCallControl::Connect, TAPI 3.0 calls TSPI_lineMakeCall in the TSP. After a call is established, the MSP and TSP can communicate as necessary.

When a call is disconnecting, it is up to the MSP and TSP to communicate about tearing down the call. Tapi3.dll will call TSPI_lineDrop if the application calls Disconnect.


H323 MSP

The H323 MSP (H323msp.dll), when paired with its TSP (h323.tsp), allows an application to make and receive video and audio calls using the H.323 protocol for IP telephony.

The H323 MSP has been enhanced in Windows 2000 SP1 to enable H323-SDP bridge terminals. It now exposes the IH323LineEx and IKeyFrameControl interfaces.

The H323 MSP is installed with Windows 2000.


IPConf MSP

The IPConf MSP (Confmsp.dll), when paired with its TSP (IPconf.tsp), provides conferencing access to Internet Protocol (IP) networks, such as the Internet and many corporate intranets. In addition to the standard MSPI methods, this MSP exposes interfaces that allow control over individual participants in a conference.

Please see IPConf MSP Interfaces for a summary of provider-specific interfaces exposed by this MSP.

The IPConf MSP has been enhanced in Windows 2000 SP1 to enable H323-SDP bridge terminals. It now additionally exposes the IMulticastControl interface.

The IPConf MSP is installed with Windows 2000.


Raw Channel Access MSP

The Raw Channel Access MSP (Rcsmsp.dll) does streaming via ksproxy to RCA, which allows streaming over connection-oriented Network Driver Interface Specification (NDIS) devices such as ATM and ISDN cards. The RCA MSP is created by the ndptsp, which is the TSP provided for NDIS WAN adapters. With the Windows 2000 release, only audio streaming is implemented.

The Raw Channel Access TSP is installed with Windows 2000.


Third Party MSP

Specialized communications hardware typically arrives with one or more TSPs and MSPs specific to the device. Documentation for the device should indicate capabilities and give programming guidelines.


Wave MSP

The Wave MSP (Wavemsp.dll) fits legacy TSPs written prior to the introduction of MSPs into TAPI 3.0's MSP-based streaming architecture. Some of the legacy TSPs expose wave device identifiers, which were a means for the application to control streaming under TAPI 2.1. Tapi3.dll uses the Wave MSP for any TSP that does not have its own MSP but that has a wave device.

The Wave MSP is installed with Windows 2000.


Media Service Provider Interface (MSPI)

The Media Service Provider Interface (MSPI) is a set of interfaces and methods implemented by an MSP to allow a TAPI 3.0 application control over media transport during a communications session. An MSP handles the device-specific and protocol-specific mechanisms needed to enact these controls, and communicates with its paired TSP or an application through use of the methods provided in the MSPI.

The following section (Media Service Provider Interface (MSPI) Reference) details the interfaces an MSP exposes in order to interact with the Microsoft Telephony environment.

In addition, an MSP may expose provider-specific private interfaces and methods to further assist in media control. For example, the IP Conference MSP exposes interfaces that provide participant control. See Provider-Specific Interfaces for information on how private objects work and IPConf MSP Interfaces for a reference listing of IPConf.

The majority of the programming effort in creating an MSP is highly specific to a given platform, device, and transport protocol, and is outside the scope of this document. However, Microsoft supplies a set of MSP base classes, which will be useful to most MSP authors. See TAPI 3.0 MSP Base Classes for information on using these classes.

The ITMSPAddress interface represents a media service provider to the TAPI DLL. This interface is not used by or exposed to an end-user application. The TAPI 3.0 DLL calls CoCreateInstance on this interface to create the main MSP object. Methods on this object allow an application to load and unload the MSP, receive information from a TSP, and create the ITStreamControl interface, which is exposed on the call object.

The ITSubStreamControl and ITSubStream interfaces provide parallel methods with respect to substreams. Substream support is optional. All other interfaces must be implemented by an MSP.


Media Service Provider Interface (MSPI) Reference

This document outlines the interfaces that provide methods that allow an MSP to interact with the Microsoft Telephony environment and allow a TAPI 3.0 application to use an MSP's media controls.

Media Service Provider Interface interfaces | Description | Required?
ITMSPAddress | Exposed only to TAPI. Main MSP interface for the TAPI DLL. TAPI 3.0 calls CoCreateInstance on this interface to create the MSP object. | Yes
ITStream | Exposed to applications. Provides methods that allow an application to retrieve information on a stream, to start, pause, or stop it, and to select or unselect terminals on a stream. | Yes
ITStreamControl | Exposed to applications. Provides methods that allow an application to create or remove streams. | Yes
IEnumStream | Exposed to applications. Enumerator interface for ITStream. | Yes
ITSubStream | Exposed to applications. Provides methods that allow an application to retrieve information on a substream, to start, pause, or stop it, and to select or unselect terminals. | Optional
ITSubStreamControl | Exposed to applications. Provides methods that allow an application to create or remove substreams. | Optional
IEnumSubStream | Exposed to applications. Enumerator interface for ITSubStream. | Optional
ITTerminal | Exposed to applications. Gets information on the Terminal object, such as terminal call and media supported. | Yes
ITTerminalSupport | Exposed to applications. Provides methods to query on available terminals and create additional terminals. | Yes
ITTerminalSupport2 | Exposed to applications. Retrieves information about pluggable terminal classes and superclasses; derives from the ITTerminalSupport interface. | TBD

Media Service Provider Interface Types

MSP_ADDRESS_EVENT
MSP_CALL_EVENT
MSP_EVENT
MSP_EVENT_INFO

See Also

Media Service Provider Interface (MSPI)


IEnumStream

The IEnumStream interface provides COM-standard enumeration methods for the ITStream interface. The ITStreamControl::EnumerateStreams and ITParticipant::EnumerateStreams methods return a pointer to IEnumStream.

Methods in Vtable Order

IUnknown Methods

IEnumStream methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to beginning of enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


IEnumStream::Clone

Creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumStream **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumStream interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumStream, ITStream


IEnumStream::Next

Gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITStream **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITStream pointers returned.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumStream, ITStream


IEnumStream::Reset

Resets to beginning of enumeration sequence.

HRESULT Reset(void);

Parameters

This enumeration has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumStream, ITStream


IEnumStream::Skip

Skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumStream, ITStream


IEnumSubStream

The IEnumSubStream interface provides COM-standard enumeration methods for the ITSubStream interface. The ITSubStreamControl::EnumerateSubStreams method returns a pointer to IEnumSubStream.

Methods in Vtable Order

IUnknown Methods

IEnumSubStream methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Reset | Resets to beginning of enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream


IEnumSubStream::Clone

Creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumSubStream **ppEnum
);

Parameters

ppEnum
[out, retval] Pointer to new IEnumSubStream interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnum parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_UNEXPECTED | Failed for unknown reasons.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumSubStream, ITSubStream


IEnumSubStream::Next

Gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG celt,
  ITSubStream **ppElements,
  ULONG *pceltFetched
);

Parameters

celt
[in] Number of elements requested.
ppElements
[out, size_is(celt)] Pointer to ITSubStream pointers returned.
pceltFetched
[out] Pointer to number of elements actually supplied. May be NULL if celt is one.

Return Values

Value | Meaning
S_OK | Method returned celt number of elements.
S_FALSE | Number of elements remaining was less than celt.
E_POINTER | The ppElements parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumSubStream, ITSubStream


IEnumSubStream::Reset

Resets to beginning of enumeration sequence.

HRESULT Reset(void);

Parameters

This enumeration has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumSubStream, ITSubStream


IEnumSubStream::Skip

Skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

Value | Meaning
S_OK | Number of elements skipped was celt.
S_FALSE | Number of elements skipped was not celt.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), IEnumSubStream, ITSubStream


ITMSPAddress

ITMSPAddress is implemented by the MSP and represents a media service provider to the TAPI DLL. It is not exposed to end-user or server applications. TAPI 3.0 will call CoCreateInstance on this interface to create the MSP object.

Methods in Vtable Order

IUnknown Methods

ITMSPAddress methods | Description
Initialize | Called when the MSP is loaded.
Shutdown | Called when the MSP is unloaded.
CreateMSPCall | Create an ITStreamControl object representing a new TAPI call.
ShutdownMSPCall | Called when the call is being disconnected.
ReceiveTSPData | Called when the TSP sends asynchronous data to the MSP.
GetEvent | Gets event information.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl, ITStream, ITSubStreamControl, ITSubStream


ITMSPAddress::Initialize

This method is called when the MSP is loaded.

HRESULT Initialize(
  MSP_HANDLE hEvent
);

Parameters

hEvent
[in] TAPI 3.0's handle for this MSP.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform operation.

Remarks

If an MSP is written using the MSP base classes, this method initializes data members, creates the Terminal Manager, and calls Start on the global MSP thread object.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITMSPAddress


ITMSPAddress::Shutdown

This method is called when the MSP is unloaded. Shutdown will be called once per address object.

HRESULT Shutdown();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.

Remarks

This method releases the terminals and releases the Terminal Manager. It releases all unprocessed events, and calls Stop on the global MSP thread object. When this function is called, no call should be alive. However, bugs in the application may keep calls or terminals around.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITMSPAddress


ITMSPAddress::CreateMSPCall

The CreateMSPCallCreate method creates an MSP Call object. TAPI aggregates this onto the main Call object and exposes the ITStreamControl interface.

HRESULT CreateMSPCall(
  MSP_HANDLE hCall,
  DWORD dwReserved,
  DWORD dwMediaType,
  IUnknown *pOuterUnknown,
  IUnknown **ppStreamControl
);

Parameters

hCall
[in] Handle for this MSP.
dwReserved
[in] Reserved value – will be 0.
dwMediaType
[in] Indicates media types required for the call.
pOuterUnknown
[in] The pointer to the IUnknown interface on the TAPI 3.0 call object. Since the MSP Call object is aggregated in the TAPI 3.0 call object, it needs to know the outer IUnknown.
ppStreamControl
[out] Pointer to IUnknown interface pointer of ITStreamControl interface for newly created call.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | The MSP failed to initialize.
E_POINTER | pMSPCallback is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALIDMEDIATYPE | dwMediaType is not a valid media type.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITMSPAddress


ITMSPAddress::ReceiveTSPData

This method is called by TAPI 3.0 when the TSP sends asynchronous data to the MSP. If the TSP sends the LINE_SENDMSPDATA message with the htCall set to NULL, pMSPCall will be NULL. If the TSP does specify the htCall, pMSPCall will correspond to the call created in CreateMSPCall.

HRESULT ReceiveTSPData(
  IUnknown *pMSPCall,
  BYTE *pBuffer,
  DWORD dwSize
);

Parameters

pMSPCall
[in] Pointer to IUnknown interface of the MSP Call object.
pBuffer
[in, size_is(dwSize)] Pointer to opaque buffer from the TSP.
dwSize
[in] Size, in bytes, of pBuffer.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pMSPCall or pBuffer parameter is not a valid pointer.
E_INVALIDARG | The pMSPCall parameter is NULL.
E_FAIL | The pMSPCall parameter does not point to a valid interface.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The MSP must free memory in pBuffer.

The semantics of the data passed in the buffer are specific to each TSP/MSP pair. This method simply dispatches the received buffer to the address (pMSPCall == NULL) or the indicated call (pMSPCall != NULL).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITMSPAddress


ITMSPAddress::ShutdownMSPCall

Called when the call object is being destroyed.

HRESULT ShutdownMSPCall(
  IUnknown *pStreamControl
);

Parameters

pStreamControl
[in] Pointer to IUnknown interface for the call's ITStreamControl.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pStreamControl parameter is not a valid pointer.
E_INVALIDARG | The pStreamControl parameter does not point to a valid ITStreamControl interface.

Remarks

This method is not automatically invoked when a call enters the disconnect state. The paired TSP of the MSP should notify the MSP of this call state change, but, because applications may retain the call object for information logging purposes after a disconnect, shutdown should not be called until the call object itself is released.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITMSPAddress


ITMSPAddress::GetEvent

Gets event information.

HRESULT GetEvent(
  DWORD *pdwSize,
  byte *pEventBuffer
);

Parameters

pdwSize
[in,out] Pointer to size of buffer containing event information.
pEventBuffer
[in, out, size_is(*pdwSize)] Pointer to buffer containing MSP event_info information.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
E_POINTER | The pdwSize or pEventBuffer parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_NOTENOUGHMEMORY | The pdwSize parameter was not large enough for the buffer.
TAPI_E_NOEVENT | No event has occurred.

Remarks

TAPI3 calls this method when the event handle given in initialize is signaled. TAPI will call this method repeatedly until it fails so it can get multiple events. Each call should return only one event structure.

Users of the MSP base classes: This method locks the event list.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITMSPAddress


ITStream

The ITStream interfaces expose methods that allow an application to retrieve information on a stream; to start, pause, or stop the stream; to select or unselect terminals on a stream; and to obtain a list of terminals selected on the stream.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITStream methods | Description
get_MediaType | Gets the stream's media type.
get_Direction | Gets the stream's terminal direction.
get_Name | Gets a BSTR representing the name of the stream.
StartStream | Starts the stream.
PauseStream | Pauses the stream.
StopStream | Stops the stream.
SelectTerminal | Selects an ITTerminal object onto the stream.
UnselectTerminal | Unselects the terminal from the stream.
EnumerateTerminals | Enumerates terminals selected on the stream.
get_Terminals | Creates a collection of terminals associated with the current stream. Provided for Automation client applications, such as those written in Microsoft Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl, ITSubStreamControl, ITSubStream


ITStream::EnumerateTerminals

Enumerates terminals selected on the stream. Provided for C and C++ applications. Automation client applications such as Visual Basic must use the get_Terminals method.

HRESULT EnumerateTerminals(
  IEnumTerminal **ppEnumTerminal
);

Parameters

ppEnumTerminal
[out] Pointer to an IEnumTerminal terminal enumerator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream, IEnumTerminal


ITStream::PauseStream

Pauses the stream.

HRESULT PauseStream();

Parameters

This object has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.

Remarks

The difference between pausing and stopping a stream depends on the type of transport.

If the stream pauses successfully, the MSP should fire CALL_MEDIA_EVENT with a value of CME_STREAM_INACTIVE and CALL_MEDIA_EVENT_CAUSE equaling CMC_LOCAL_REQUEST.

If the stream fails to pause, the event will be CME_STREAM_FAIL with cause CMC_LOCAL_REQUEST.

A call to StartStream restarts the stream.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


ITStream::SelectTerminal

Selects an ITTerminal object onto the stream.

HRESULT SelectTerminal(
  ITTerminal *pTerminal
);

Parameters

pTerminal
[in] Pointer to ITTerminal interface of selected terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_MAXTERMINALS | Multiple terminals have been selected on the stream, but media mixing or splitting is not possible.
TAPI_E_INVALIDTERMINAL | The terminal selected is not valid.

Remarks

Terminals can be selected at any time, irrespective of whether the transport is in a state that allows it to stream media. If the transport is in a state that allows it to stream media, and the application has not successfully invoked ITStream::PauseStream or ITStream::StopStream on the stream, or has successfully invoked ITStream::StartStream for this stream more recently than it has successfully invoked ITStream::PauseStream or ITStream::StopStream for this stream, then streaming starts automatically as soon as the terminal is selected. If a terminal is selected on the stream before the transport enters a state in which it can stream media, and no subsequent calls to StopStream or PauseStream are made, then the stream starts automatically when the transport enters a state in which it can stream media.

The CME_STREAM_ACTIVE event is generated when streaming actually starts, which may be later than the SelectTerminal call. The CME_STREAM_FAIL or CME_TERMINAL_FAIL event is generated when streaming actually fails, which may also be later than the SelectTerminal call.

A terminal can be selected onto a stream only if the results of ITTerminal::get_MediaType match ITStream::get_MediaType. In addition, some MSPs may require a match between ITTerminal::get_Direction and ITStream::get_Direction, although the interface does not enforce this.

Some MSPs may not allow more than a certain number of terminals, typically one, to be simultaneously selected on the same stream, but the interface itself does not enforce any such restriction. Selecting multiple terminals at one time on the same stream is useful, for example, to allow recording of an incoming audio stream to a file while listening to the stream on a pair of speakers.

A given terminal can be selected onto only one stream.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


ITStream::StartStream

Starts the stream.

HRESULT StartStream();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
TAPI_E_NOTERMINALSELECTED | No terminal has been selected on the stream, so it cannot be started.
TAPI_E_NOTSTOPPED | Stream has already been started.

Remarks

Streams start automatically as soon as a call is connected and ready to stream and a terminal is selected. Therefore, most applications do not need to call this method. Applications have to call this method only to start a stream that the application has previously stopped or paused by calling ITStream::StopStream or ITStream::PauseStream.

This call generates events that the application can retrieve if it has registered. Please see the Events overview for information on receiving events.

If the stream starts successfully, the MSP fires a CALL_MEDIA_EVENT with a value of CME_STREAM_ACTIVE event and CALL_MEDIA_EVENT_CAUSE equaling CMC_LOCAL_REQUEST.

If the stream fails to pause, the MSP fires a CME_STREAM_FAIL event with cause CMC_LOCAL_REQUEST.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


ITStream::StopStream

Stops the stream.

HRESULT StopStream();

Parameters

This interface has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.
TAPI_E_NOTSUPPORTED | The provider does not support this operation.

Remarks

An application can call this method to stop a stream. The difference between pausing a stream and stopping a stream depends on the type of transport used for the call.

This call generates events that the application can retrieve if it has registered. Please see the Events overview for information on receiving events.

If the stream stops successfully, the application receives a CALL_MEDIA_EVENT with a value of CME_STREAM_INACTIVE event and CALL_MEDIA_EVENT_CAUSE equaling CMC_LOCAL_REQUEST.

If the stream fails to pause, the application receives a CME_STREAM_FAIL event with cause CMC_LOCAL_REQUEST.

To subsequently restart the stream, the application must call StartStream.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


ITStream::UnselectTerminal

Unselects the terminal from the stream and stops streaming for this stream.

HRESULT UnselectTerminal(
  ITTerminal *pTerminal
);

Parameters

pTerminal
[in] Pointer to ITTerminal interface terminal to remove from stream.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALIDTERMINAL | The pTerminal parameter does not point to a valid terminal.
TAPI_E_NOTSUPPORTED | The provider does not support this operation.

Remarks

Some stream events may be received after streaming has been stopped due to delayed transmission.

Successfully unselecting the last terminal from a stream effectively ceases any existing streaming for this particular stream. Subsequently selecting the same terminal or another terminal restarts such interrupted streaming.

Reselection onto a stream with a different terminal, or a newly created one, can have unexpected effects. The filter graph may retain information from the previous terminal that fails to match the new one.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


ITStream::get_Direction

Gets the stream's terminal direction.

HRESULT get_Direction(
  TERMINAL_DIRECTION *pTD
);

Parameters

pTD
[out, retval] Pointer to TERMINAL_DIRECTION descriptor.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTD parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

Terminals of either direction can, in general, be selected on any stream whose media type matches the terminal's media type. However, some MSPs allow only terminals whose terminal direction matches the stream's terminal direction to be selected on a stream.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream, TERMINAL_DIRECTION


ITStream::get_MediaType

Gets the stream's media type.

HRESULT get_MediaType(
  long *plMediaType
);

Parameters

plMediaType
[out, retval] Pointer to media type descriptor.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plMediaType parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


ITStream::get_Name

Gets a BSTR representing the name of the stream. This name is used for informational or display purposes.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out, retval] Pointer to BSTR representation of stream's name.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream


ITStream::get_Terminals

Creates a collection of terminals associated with the current stream. Provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateTerminals method.

HRESULT get_Terminals(
  VARIANT *pTerminals
);

Parameters

pTerminals
[out, retval] Pointer to VARIANT containing an ITCollection of ITTerminal interface pointers (terminal objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminals parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream, ITCollection, ITTerminal


ITStreamControl

The ITStreamControl interface represents the media streaming features of a call and exposes methods that allow an application to enumerate, create, or remove streams.

If this interface exists, a TAPI application acquires a pointer to this interface by performing a QueryInterface on any call interface, such as ITCallInfo. This interface is not available if an MSP is not involved in the current call session.

Internal to the TAPI DLL, this interface is implemented by the MSP's call object, which is created in the ITMSPAddress::CreateMSPCall method. TAPI then aggregates this interface onto the TAPI call object and exposes it to TAPI applications.

Methods in Vtable Order

IUnknown Methods

ITStreamControl methods | Description
CreateStream | Creates a media stream.
RemoveStream | Removes a media stream.
EnumerateStreams | Enumerates streams currently available.
get_Streams | Creates a collection of streams currently available. Provided for Automation client applications, such as those written in Microsoft Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStream, ITSubStreamControl, ITSubStream


ITStreamControl::CreateStream

Creates a new media stream.

HRESULT CreateStream(
  long lMediaType,
  TERMINAL_DIRECTION td,
  ITStream **ppStream
);

Parameters

lMediaType
[in] Indicates media type for stream.
td
[in] Indicates the TERMINAL_DIRECTION.
ppStream
[out, retval] Pointer to pointer for newly created ITStream interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppStream parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALIDMEDIATYPE | The lMediaType parameter is not a valid media type.
TAPI_E_INVALIDDIRECTION | The td parameter is not a valid terminal direction.
TAPI_E_MAXSTREAMS | The maximum number of streams supported has already been reached.
TAPI_E_NOTSUPPORTED | This operation is not supported.

Remarks

Many MSPs do not support dynamic creation of streams, and simply return TAPI_E_MAXSTREAMS in their implementation of this method. Default streams are automatically available when a call is created, so most applications do not have to use this method.

Stream creation or removal may involve interaction with a remote endpoint, resulting in a CMC_REMOTE_REQUEST rather than the CMC_LOCAL_REQUEST messages that are received when a stream is stopped or started.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl, TERMINAL_DIRECTION, media type


ITStreamControl::EnumerateStreams

Enumerates currently available media streams. Provided for C and C++ applications. Automation client applications such as Visual Basic must use the get_Streams method.

HRESULT EnumerateStreams(
  IEnumStream **ppEnumStream
);

Parameters

ppEnumStream
[out] Pointer to pointer for IEnumStream enumerator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppEnumStream parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl


ITStreamControl::RemoveStream

Removes a media stream.

HRESULT RemoveStream(
  ITStream *pStream
);

Parameters

pStream
[in] Pointer to ITStream interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pStream parameter is not valid.
TAPI_E_NOTSUPPORTED | This operation is not supported.

Remarks

Some MSPs may not support the advanced concept of creating and removing streams, and simply return TAPI_E_NOTSUPPORTED.

Stream creation or removal may involve interaction with a remote endpoint, resulting in a CMC_REMOTE_REQUEST rather than the CMC_LOCAL_REQUEST messages that are received when a stream is stopped or started.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl


ITStreamControl::get_Streams

Creates a collection of media streams currently available on the call. Provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateStreams method.

HRESULT get_Streams(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITStream interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl, ITCollection, ITStream


ITSubStream

An ITSubStream is a component of an ITStream, and gives an application finer control over the media streaming. The ITSubStream interface provides methods that start, pause, or stop a substream, select or unselect terminals, and obtain a list of terminals selected on the stream.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITSubStream methods | Description
StartSubStream | Starts the substream.
PauseSubStream | Pauses the substream.
StopSubStream | Stops the substream.
SelectTerminal | Selects an ITTerminal object onto the substream.
UnselectTerminal | Unselects the terminal from the substream.
EnumerateTerminals | Enumerates terminals selected on the substream.
get_Terminals | Creates a collection of terminals associated with the current substream. Provided for Automation client applications, such as those written in Microsoft Visual Basic.
get_Stream | Retrieves pointer to ITStream interface for current substream.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl, ITStream, ITSubStreamControl


ITSubStream::EnumerateTerminals

Enumerates terminals selected on the substream. Provided for C and C++ applications. Automation client applications such as Visual Basic must use the get_Terminals method.

HRESULT EnumerateTerminals(
  IEnumTerminal **ppEnumTerminal
);

Parameters

ppEnumTerminal
[out] Pointer to an IEnumTerminal terminal enumerator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppEnumTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

This method returns only the terminals selected on the substream. Other terminals may be selected on the stream or on other substreams within the stream; those terminals are not returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream, IEnumTerminal


ITSubStream::get_Stream

Retrieves pointer to ITStream interface for current substream.

HRESULT get_Stream(
  ITStream **ppITStream
);

Parameters

ppITStream
[out, retval] Pointer to current ITStream interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppITStream parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream


ITSubStream::PauseSubStream

Pauses the substream.

HRESULT PauseSubStream();

Parameters

This interface has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_NOTSUPPORTED | This operation is not supported.

Remarks

The difference between pausing and stopping a stream depends on the type of transport.

If the substream pauses successfully, the application receives a CALL_MEDIA_EVENT with a value of CME_STREAM_INACTIVE and CALL_MEDIA_EVENT_CAUSE equaling CMC_LOCAL_REQUEST.

If the substream fails to pause, the event will be CME_STREAM_FAIL with cause CMC_LOCAL_REQUEST.

A call to StartSubStream restarts the substream.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream


ITSubStream::SelectTerminal

Selects an ITTerminal object onto the substream. See the Remarks section under ITStream::SelectTerminal for additional information.

HRESULT SelectTerminal(
  ITTerminal *pTerminal
);

Parameters

pTerminal
[in] Pointer to ITTerminal interface of selected terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_MAXTERMINALS | Multiple terminals have been selected on the substream, but media mixing or splitting is not possible.
TAPI_E_INVALIDTERMINAL | The terminal selected is not valid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream, ITStream::SelectTerminal


ITSubStream::StartSubStream

Starts the substream. See the Remarks section under ITStream::StartStream for additional information.

HRESULT StartSubStream();

Parameters

This interface has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_NOTERMINALSELECTED | No terminal has been selected on the substream so it cannot be started.
TAPI_E_NOTSTOPPED | Substream has already been started.
TAPI_E_NOTSUPPORTED | This operation is not supported.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream


ITSubStream::StopSubStream

Stops the substream. For additional information, see ITStream::StopStream.

HRESULT StopSubStream();

Parameters

This interface has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_NOTSUPPORTED | The provider does not support this operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream


ITSubStream::UnselectTerminal

Unselects the terminal from the substream.

HRESULT UnselectTerminal(
  ITTerminal *pTerminal
);

Parameters

pTerminal
[in] Pointer to ITTerminal interface terminal to remove from stream.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALIDTERMINAL | The pTerminal parameter does not point to a valid terminal.
TAPI_E_NOTSUPPORTED | The provider does not support this operation.

Remarks

Some stream events may be received after streaming has been stopped due to delayed transmission.

Successfully unselecting the last terminal from a substream effectively ceases any existing streaming for this particular substream. Subsequently selecting the same terminal or another terminal restarts such interrupted streaming.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream


ITSubStream::get_Terminals

Creates a collection of terminals associated with the current substream. Provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateTerminals method.

HRESULT get_Terminals(
  VARIANT *pTerminals
);

Parameters

pTerminals
[out, retval] Pointer to VARIANT containing an ITCollection of ITTerminal interface pointers (terminal objects).

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminals parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

This method returns only the terminals selected on the substream. Other terminals may be selected on the stream or on other substreams within the stream; those terminals are not returned.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStream, ITCollection, ITTerminal


ITSubStreamControl

The interface exposes methods that allow an application to enumerate, create, or remove substreams. Many MSPs do not support this interface.

A pointer to this interface can be obtained by calling QueryInterface on the stream object.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITSubStreamControl methods | Description
CreateSubStream | Creates a substream.
RemoveSubStream | Removes a substream.
EnumerateSubStreams | Enumerates substreams.
get_SubStreams | Creates a collection of substreams associated with the current stream. Provided for Automation client applications, such as those written in Microsoft Visual Basic.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITStreamControl, ITStream, ITSubStream


ITSubStreamControl::CreateSubStream

Creates a substream.

HRESULT CreateSubStream(
  ITSubStream **ppSubStream
);

Parameters

ppSubStream
[out, retval] Pointer to ITSubStream interface created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppSubStream parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_MAXSTREAMS | Substream cannot be created because the maximum number of streams has already been reached.

Remarks

Many MSPs do not support dynamic creation of substreams, and simply return TAPI_E_MAXSTREAMS in their implementation of this method.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStreamControl


ITSubStreamControl::EnumerateSubStreams

Enumerates currently available media substreams. Provided for C and C++ applications. Automation client applications such as Visual Basic must use the get_SubStreams method.

HRESULT EnumerateSubStreams(
  IEnumSubStream **ppEnumSubStream
);

Parameters

ppEnumSubStream
[out] Pointer to IEnumSubStream enumeration of substreams.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The ppEnumSubStream parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStreamControl


ITSubStreamControl::RemoveSubStream

Removes a substream.

HRESULT RemoveSubStream(
  ITSubStream *pSubStream
);

Parameters

pSubStream
[in] Pointer to ITSubStream to be removed.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pSubStream parameter does not point to a valid interface.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_INVALIDSTREAM | The pSubStream parameter does not point to a valid substream.

Remarks

Some MSPs may not support the advanced concept of creating and removing substreams, and simply return TAPI_E_NOTSUPPORTED.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStreamControl


ITSubStreamControl::get_SubStreams

Creates a collection of substreams currently available. Provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateSubStreams method.

HRESULT get_SubStreams(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to VARIANT containing an ITCollection of ITSubstream interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_UNEXPECTED | The call appears to have been shut down.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Media Service Provider Interface (MSPI), ITSubStreamControl, ITCollection, ITSubstream


ITTerminal

The ITTerminal interface is the base interface for a Terminal object. This object, and the interface, is available only when an MSP exists. It provides methods that allow an application to obtain information such as terminal class and media supported.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTerminal methods | Description
get_Name | Gets a descriptive name of the terminal.
get_State | Gets a TERMINAL_STATE descriptor of the terminal's current state.
get_TerminalType | Gets the TERMINAL_TYPE descriptor of the terminal's type.
get_TerminalClass | Gets the terminal class of the terminal.
get_MediaType | Gets the media type supported by the terminal.
get_Direction | Gets the TERMINAL_DIRECTION descriptor of the media stream direction for the terminal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object, Terminal Object Interfaces


ITTerminal::get_Direction

Gets a TERMINAL_DIRECTION descriptor of the media stream direction for the terminal.

HRESULT get_Direction(
  TERMINAL_DIRECTION *pDirection
);

Parameters

pDirection
[out, retval] TERMINAL_DIRECTION descriptor of the media stream direction for the terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pDirection parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminal, Terminal Object, Terminal Object Interfaces, TERMINAL_DIRECTION


ITTerminal::get_MediaType

Determines the media that this terminal supports.

HRESULT get_MediaType(
  long *plMediaType
);

Parameters

plMediaType
[out, retval] Pointer to media type.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The plMediaType parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminal, Terminal Object, Terminal Object Interfaces


ITTerminal::get_Name

Gets a descriptive name of the terminal. The name must be usable to the user.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out, retval] Pointer to BSTR containing the name of the terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppName parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppName parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminal, Terminal Object, Terminal Object Interfaces


ITTerminal::get_State

Gets the current state of the terminal.

HRESULT get_State(
  TERMINAL_STATE *pTerminalState
);

Parameters

pTerminalState
[out, retval] Pointer to a TERMINAL_STATE enum member.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pTerminalState parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminal, Terminal Object, Terminal Object Interfaces, TERMINAL_STATE


ITTerminal::get_TerminalClass

Gets the Terminal Class of the terminal.

HRESULT get_TerminalClass(
  BSTR *ppTerminalClass
);

Parameters

ppTerminalClass
[out, retval] Pointer to BSTR representation of the Terminal Class of the terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTerminalClass parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

The application must use SysFreeString to free the memory allocated for the ppTerminalClass parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminal, Terminal Object, Terminal Object Interfaces


ITTerminal::get_TerminalType

Gets the TERMINAL_TYPE of the terminal.

HRESULT get_TerminalType(
  TERMINAL_TYPE *pType
);

Parameters

pType
[out, retval] Pointer to a TERMINAL_TYPE.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pType parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminal, Terminal Object, Terminal Object Interfaces, TERMINAL_TYPE


ITTerminalSupport

The ITTerminalSupport interface is exposed on an Address object only if an MSP exists. The methods of this interface allow an application to discover available terminals and/or create one, and get pointers to required Terminal objects.

An ITTerminalSupport pointer can be obtained by calling QueryInterface on any Address interface, such as ITAddress. If E_NOINTERFACE is returned, the service provider associated with the address does not support media controls.

The ITTerminalSupport2 interface is derived from the ITTerminalSupport interface. ITTerminalSupport2 supports the retrieval of information about pluggable terminal classes and superclasses by C, C++, and scripting applications.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTerminalSupport methods | Description
get_StaticTerminals | Creates a collection of the currently available static terminals. Provided for Automation client applications, such as those written in Microsoft Visual Basic.
EnumerateStaticTerminals | Enumerates the currently available static terminals that are associated with the address.
get_DynamicTerminalClasses | Creates a collection of currently available dynamic terminals. Provided for Automation client applications, such as those written in Visual Basic.
EnumerateDynamicTerminalClasses | Enumerates the currently available dynamic terminal classes that are supported.
CreateTerminal | Creates a new terminal based on the dynamic terminal class.
GetDefaultStaticTerminal | Gets the default static terminal for the media specified.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

Terminal Object, Terminal Object Interfaces, Address Object, ITTerminalSupport2


ITTerminalSupport::CreateTerminal

Creates and initializes a new ITTerminal object based on the dynamic terminal class and media. The terminal class is identified by a GUID. The GUID must be converted to a string using StringFromIID to pass to this method.

HRESULT CreateTerminal(
  BSTR pTerminalClass,
  long lMediaType,
  TERMINAL_DIRECTION Direction,
  ITTerminal **ppTerminal
);

Parameters

pTerminalClass
[in] Pointer to BSTR containing the terminal class (GUID) for the new terminal object.
lMediaType
[in] Pointer to the media type for the new terminal object.
Direction
[in] TERMINAL_DIRECTION descriptor of the terminal direction.
ppTerminal
[out, retval] Pointer to the ITTerminal object created.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pTerminalClass or lMediaType parameter is not valid.
E_POINTER | The ppTerminal parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to create the ITTerminal object.
E_MEDIATYPE | The lMediaType parameter is invalid.
TAPI_E_NOTSUPPORTED | Dynamic terminal creation is not supported.

Remarks

The application must use SysAllocString to allocate memory for the pTerminalClass parameter and use SysFreeString to free the memory when the variable is no longer needed.

Once a terminal is created, it can be selected onto only one call.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport, terminal class, media type, TERMINAL_DIRECTION, Terminal Object, Terminal Object Interfaces, Address Object


ITTerminalSupport::EnumerateDynamicTerminalClasses

Enumerates the currently available dynamic terminal classes that are supported. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_DynamicTerminalClasses method.

HRESULT EnumerateDynamicTerminalClasses(
  IEnumTerminalClass **ppTerminalClassEnumerator
);

Parameters

ppTerminalClassEnumerator
[out, retval] Pointer to an IEnumTerminalClass enumerator. TAPI returns these classes as GUIDs.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTerminalClassEnumerator parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Remarks

An application calls this method to find out which dynamic terminal classes are supported by this address in a call to ITTerminalSupport::CreateTerminal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport, terminal classes, Terminal Object, Terminal Object Interfaces, Address Object, Terminal Classes


ITTerminalSupport::EnumerateStaticTerminals

Enumerates the currently available static terminals associated with the address. This method is provided for C and C++ applications. Automation client applications, such as those written in Visual Basic, must use the get_StaticTerminals method.

HRESULT EnumerateStaticTerminals(
  IEnumTerminal **ppTerminalEnumerator
);

Parameters

ppTerminalEnumerator
[out, retval] Pointer to an IEnumTerminal enumerator.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The ppTerminalEnumerator parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport, Terminal Object, Terminal Object Interfaces, Address Object


ITTerminalSupport::GetDefaultStaticTerminal

Gets the default static terminal for the media type specified.

HRESULT GetDefaultStaticTerminal(
  long lMediaType,
  TERMINAL_DIRECTION Direction,
  ITTerminal **ppTerminal
);

Parameters

lMediaType
[in] Media type of the required terminal.
Direction
[in] TERMINAL_DIRECTION descriptor of the terminal direction.
ppTerminal
[out, retval] Pointer to the ITTerminal interface. NULL if no terminal is available.

Return Values

Value | Meaning
S_OK | Method succeeded.
S_FALSE | No terminal is available. *ppTerminal will be returned as NULL.
E_FAIL | Unspecified error.
E_POINTER | The lMediaType parameter is not a valid pointer.
E_MEDIATYPE | The lMediaType parameter is not a valid media type.
E_OUTOFMEMORY | Insufficient memory exists to create the Terminal object.

Remarks

This method does not return dynamic terminals. For example, having a media type of TAPIMEDIATYPE_VIDEO and a terminal direction of TD_RENDER defines a dynamic terminal; this method will fail with those parameters.

The default static terminal returned by this method is one of the static terminals returned by ITTerminalSupport::EnumerateStaticTerminals or ITTerminalSupport::get_StaticTerminals. Usually, the default terminal is the one selected as "preferred device" in Control Panel's "Sounds and Multimedia Properties" applet.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport, Media type, TERMINAL_DIRECTION, Terminal Object, Terminal Object Interfaces, Address Object


ITTerminalSupport::get_DynamicTerminalClasses

Creates a collection of currently available dynamic terminals. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateDynamicTerminalClasses method.

HRESULT get_DynamicTerminalClasses(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to a VARIANT containing an ITCollection of terminal classes, in a string (BSTR) format.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.
E_POINTER | The pVariant parameter is not a valid pointer.

Remarks

An application calls this method to find out which dynamic terminal classes are supported by this address in a call to ITTerminalSupport::CreateTerminal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport, Terminal Object, Terminal Object Interfaces, Address Object, Terminal Class


ITTerminalSupport::get_StaticTerminals

Creates a collection of currently available static terminals. This method is provided for Automation client applications, such as those written in Visual Basic. C and C++ applications must use the EnumerateStaticTerminals method.

HRESULT get_StaticTerminals(
  VARIANT *pVariant
);

Parameters

pVariant
[out, retval] Pointer to a VARIANT, which TAPI will fill in with an ITCollection of ITTerminal interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pVariant parameter is not a valid pointer.
E_OUTOFMEMORY | Insufficient memory exists to perform the operation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport, Terminal Object, Terminal Object Interfaces, Address Object, ITCollection, ITTerminal


ITTerminalSupport2

[This is preliminary documentation and subject to change.]

The ITTerminalSupport2 interface is derived from the ITTerminalSupport interface. ITTerminalSupport2 supports the retrieval of information about pluggable terminal classes and superclasses by C, C++, and scripting applications.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTerminalSupport2 methods | Description
get_PluggableSuperclasses | Gets a collection of ITPluggableTerminalSuperclassInfo superclass information interfaces.
EnumeratePluggableSuperclasses | Gets an IEnumPluggableSuperclassInfo enumeration of pluggable terminal superclasses registered on the current system.
get_PluggableTerminalClasses | Gets a collection of ITPluggableTerminalClassInfo terminal class information interfaces.
EnumeratePluggableTerminalClasses | Gets an IEnumPluggableTerminalClassInfo enumeration of the pluggable terminal classes registered under a given superclass.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport, ITPluggableTerminalSuperclassInfo, IEnumPluggableSuperclassInfo, ITPluggableTerminalClassInfo, IEnumPluggableTerminalClassInfo


ITTerminalSupport2::EnumeratePluggableSuperclasses

[This is preliminary documentation and subject to change.]

The EnumeratePluggableSuperclasses method enumerates the pluggable terminal superclasses registered on the current system.

This method is intended for Visual Basic and scripting applications. C/C++ applications must use the get_PluggableSuperClasses method.

HRESULT EnumeratePluggableSuperclasses(
  IEnumPluggableSuperclassInfo ** ppSuperclassEnumerator
);

Parameters

ppSuperclassEnumerator
[out,retval] Pointer to the IEnumPluggableSuperclassInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | The method failed.
E_POINTER | The ppSuperclassEnumerator parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport2, IEnumPluggableSuperclassInfo


ITTerminalSupport2::EnumeratePluggableTerminalClasses

[This is preliminary documentation and subject to change.]

The EnumeratePluggableTerminalClasses method enumerates the pluggable terminal classes registered under a given superclass.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_PluggableTerminalClasses method.

HRESULT EnumeratePluggableTerminalClasses(
  CLSID iidTerminalSuperclass,
  long lMediaType,
  IEnumPluggableTerminalClassInfo ** ppClassEnumerator
);

Parameters

iidTerminalSuperclass
[in] CLSID for the terminal superclass.
lMediaType
[in] Bitwise ORed list of media types supported by the terminal classes.
ppClassEnumerator
[out,retval] Pointer to the IEnumPluggableTerminalClassInfo interface.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The lMediaType parameter is not valid.
E_FAIL | The method failed.
E_POINTER | The ppClassEnumerator parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport2, IEnumPluggableTerminalClassInfo


ITTerminalSupport2::get_PluggableSuperclasses

[This is preliminary documentation and subject to change.]

The get_PluggableSuperclasses method returns a collection of ITPluggableTerminalSuperclassInfo superclass information interface pointers.

This method is intended for Visual Basic and scripting applications. C/C++ applications can use the EnumeratePluggableSuperclasses method.

HRESULT get_PluggableSuperclasses(
  VARIANT * pVariant
);

Parameters

pVariant
[out,retval] Pointer to a VARIANT containing an ITCollection of ITPluggableTerminalSuperclassInfo interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | The method failed.
E_POINTER | The pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport2, ITCollection, ITPluggableTerminalSuperclassInfo


ITTerminalSupport2::get_PluggableTerminalClasses

[This is preliminary documentation and subject to change.]

The get_PluggableTerminalClasses method returns a collection of ITPluggableTerminalClassInfo terminal class information interface pointers.

This method is intended for Visual Basic and scripting applications. C/C++ applications can use the EnumeratePluggableTerminalClasses method.

HRESULT get_PluggableTerminalClasses(
  BSTR bstrTerminalSuperclass,
  long lMediaType,
  VARIANT * pVariant
);

Parameters

bstrTerminalSuperclass
[in] The BSTR representation of the CLSID for the terminal superclass.
lMediaType
[in] Bitwise ORed list of media types supported by the terminal classes.
pVariant
[out,retval] Pointer to a VARIANT containing an ITCollection of ITPluggableTerminalClassInfo interface pointers.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The lMediaType parameter is not valid.
E_FAIL | The method failed.
E_POINTER | The bstrTerminalSuperclass or pVariant parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Tapi3.h.
Library: Use Uuid.lib.

See Also

ITTerminalSupport2, ITPluggableTerminalClassInfo, ITCollection


Media Service Provider Types

MSP_ADDRESS_EVENT

MSP_CALL_EVENT

MSP_CALL_EVENT_CAUSE

MSP_EVENT

MSP_EVENT_INFO

MSP_ADDRESS_EVENT_INFO

MSP_CALL_EVENT_INFO

MSP_TSP_DATA

MSP_PRIVATE_EVENT_INFO


MSP_ADDRESS_EVENT

This constant is returned within the MSP_EVENT_INFO struct by the GetEvent method when MSP_EVENT is ME_ADDRESS_EVENT.

typedef enum
{
  ADDRESS_TERMINAL_AVAILABLE,
  ADDRESS_TERMINAL_UNAVAILABLE
} MSP_ADDRESS_EVENT;

Members

ADDRESS_TERMINAL_AVAILABLE
A new terminal arrived by PNP.
ADDRESS_TERMINAL_UNAVAILABLE
A terminal has been removed by PNP.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT, MSP_EVENT_INFO, ITMSPAddress::GetEvent


MSP_CALL_EVENT

This constant is returned within the MSP_EVENT_INFO struct by the GetEvent method when MSP_EVENT is ME_CALL_EVENT.

typedef enum
{
  CALL_NEW_STREAM,
  CALL_STREAM_FAIL,
  CALL_TERMINAL_FAIL,
  CALL_STREAM_NOT_USED,
  CALL_STREAM_ACTIVE,
  CALL_STREAM_INACTIVE,
} MSP_CALL_EVENT;

Members

CALL_NEW_STREAM
A new stream is created by the call. The application can choose to select a terminal or delete the stream from the call.
CALL_STREAM_FAIL
Setup of the stream failed or the stream fails to start.
CALL_TERMINAL_FAIL
The terminal failed to connect.
CALL_STREAM_NOT_USED
The stream is not used in the call (the remote party rejected it).
CALL_STREAM_ACTIVE
The application needs this event to decide when a stream can be used to send and receive data. It is fired when the streams enter running state (the timing of which is determined by the TSP).
CALL_STREAM_INACTIVE
No more data can be sent to or received from this stream. This happens when a send stream has sent all its data, or when a receive stream stops receiving data.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT, MSP_EVENT_INFO, ITMSPAddress::GetEvent


MSP_CALL_EVENT_CAUSE

This constant is returned within the MSP_EVENT_INFO struct by the GetEvent method when MSP_EVENT is ME_CALL_EVENT.

typedef enum
{
  CALL_CAUSE_UNKNOWN,
  CALL_CAUSE_BAD_DEVICE,
  CALL_CAUSE_CONNECT_FAIL,
  CALL_CAUSE_LOCAL_REQUEST,
  CALL_CAUSE_REMOTE_REQUEST,
  CALL_CAUSE_MEDIA_TIMEOUT,
  CALL_CAUSE_MEDIA_RECOVERED
} MSP_CALL_EVENT_CAUSE;

Members

CALL_CAUSE_UNKNOWN
Call event cause is unknown.
CALL_CAUSE_BAD_DEVICE
A bad device caused failure, for either STREAM_FAIL or TERMINAL_FAIL.
CALL_CAUSE_CONNECT_FAIL
Either connecting the stream failed or connecting the terminal failed. Note that if a terminal cannot be connected to a stream, the application will get a TERMINAL_FAIL event with CMC_CONNECT_FAIL. If this stream failed because the terminal is the only one to use, the application will also get a STREAM_FAIL event with CMC_CONNECT_FAIL.
CALL_CAUSE_LOCAL_REQUEST
The event is the result of the application calling a method on the stream.
CALL_CAUSE_REMOTE_REQUEST
The event is the result of the remote endpoint's request.
CALL_CAUSE_MEDIA_TIMEOUT
The media that carries the stream is temporarily not available.
CALL_CAUSE_MEDIA_RECOVERED
The media that carries the stream is back to normal from a temporary denial of service.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT, MSP_EVENT_INFO, ITMSPAddress::GetEvent


MSP_EVENT

Defines type of event information contained in MSP_EVENT_INFO.

typedef enum
{
  ME_ADDRESS_EVENT,
  ME_CALL_EVENT,
  ME_TSP_DATA,
  ME_PRIVATE_EVENT
} MSP_EVENT;

Members

ME_ADDRESS_EVENT
The event buffer is an MSP_ADDRESS_EVENT_INFO structure.
ME_CALL_EVENT
The event buffer is an MSP_CALL_EVENT_INFO structure.
ME_TSP_DATA
The event buffer is an MSP_TSP_DATA structure.
ME_PRIVATE_EVENT
The event buffer is an MSP_PRIVATE_EVENT_INFO structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT_INFO, ITMSPAddress::GetEvent


MSP_EVENT_INFO

Defines type of event, returned by the GetEvent method.

typedef struct
{
  DWORD               dwSize;
  MSP_EVENT           Event;
  MSP_HANDLE          hCall;

  [switch_type(MSP_EVENT), switch_is((MSP_EVENT)Event)]
  union
  {
      [case(ME_ADDRESS_EVENT)]
      struct
      {
          MSP_ADDRESS_EVENT   Type;
          ITTerminal        * pTerminal;
      } MSP_ADDRESS_EVENT_INFO;

      [case(ME_CALL_EVENT)]
      struct
      {
          MSP_CALL_EVENT       Type;
          MSP_CALL_EVENT_CAUSE   Cause;
          ITStream           * pStream;
          ITTerminal         * pTerminal;
          HRESULT              hrError;
      } MSP_CALL_EVENT_INFO;

      [case(ME_TSP_DATA)]
      struct
      {
          DWORD               dwBufferSize;
          BYTE                pBuffer[1];
      } MSP_TSP_DATA;

      [case(ME_PRIVATE_EVENT)]
      struct
      {
          IDispatch         * pEvent;
      } MSP_PRIVATE_EVENT_INFO;

  };

} MSP_EVENT_INFO;

Members

dwSize
Total size of structure returned.
Event
MSP event type.
hCall
MSP handle; may be NULL.
MSP_ADDRESS_EVENT_INFO
Struct returned if MSP event is ME_ADDRESS_EVENT.
MSP_CALL_EVENT_INFO
Struct returned if MSP event is ME_CALL_EVENT.
MSP_TSP_DATA
Struct returned if MSP event is ME_TSP_DATA.
MSP_PRIVATE_EVENT_INFO
Struct returned if MSP event is ME_PRIVATE_EVENT.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), ITMSPAddress::GetEvent


MSP_ADDRESS_EVENT_INFO

This structure is contained within MSP_EVENT_INFO if the MSP event is ME_ADDRESS_EVENT.

struct
{
  MSP_ADDRESS_EVENT   Type;
  ITTerminal        * pTerminal;
} MSP_ADDRESS_EVENT_INFO;

Members

Type
Describes msp address event of event that has occurred.
pTerminal
Pointer to ITTerminal interface.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT_INFO, ITMSPAddress::GetEvent


MSP_CALL_EVENT_INFO

This structure is contained within MSP_EVENT_INFO if the MSP event is ME_CALL_EVENT.

struct
{
  MSP_CALL_EVENT       Type;
  ITStream           * pStream;
  ITTerminal         * pTerminal;
  HRESULT              hrError;
} MSP_CALL_EVENT_INFO;

Members

Type
Indicates type of MSP_CALL_EVENT that has occurred.
pStream
Pointer to ITStream interface on which event occurred.
pTerminal
Pointer to ITTerminal interface on which event occurred.
hrError
Indicates error, if one has happened.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT_INFO, ITMSPAddress::GetEvent


MSP_TSP_DATA

This structure is contained within MSP_EVENT_INFO if the MSP event is ME_TSP_DATA.

struct
{
  DWORD               dwBufferSize;
  BYTE                pBuffer[1];
} MSP_TSP_DATA;

Members

dwBufferSize
Size of buffer returned.
pBuffer
Pointer to buffer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT_INFO, ITMSPAddress::GetEvent


MSP_PRIVATE_EVENT_INFO

This structure is contained within MSP_EVENT_INFO if the MSP event is ME_PRIVATE_EVENT.

struct
{
  IDispatch         * pEvent;
} MSP_PRIVATE_EVENT_INFO;

Members

pEvent
Pointer to IDispatch interface of private object on which event has occurred.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Tapi3.h.

See Also

Media Service Provider Interface (MSPI), MSP_EVENT_INFO, ITMSPAddress::GetEvent


Writing a Media Service Provider

A media service provider must implement a minimum subset of MSPI interfaces: ITMSPAddress, ITTerminalSupport, ITStreamControl, and ITStream. SubStream support is optional. In addition, a given MSP may implement additional methods, such as controls required for specialized hardware.

The following material documents:

  • The TAPI 3.0 MSP Base Classes, which are a set of C++ classes designed to simplify the task of building a DirectShow-based MSP. The base classes implement all the MSPI interfaces in a generic manner. Different MSPs can override MSP-specific functions and provide their own implementations.
  • The TAPI 3.0 Terminal Manager, which provides interfaces and methods used by an MSP to control terminals.
  • Pluggable Terminals, which allow an application instead of an MSP to create terminals. Developers who are already experienced at writing service providers will be the primary creators of pluggable terminals. The initial version implemented for this release is aimed at conferencing server applications that need to add non-Windows 2000 or non-multicast clients to TAPI 3.0 multi-party SDP/IP multicast conferences.


TAPI 3.0 MSP Base Classes

This document describes the design and use of the MSP Base Classes. Use of these classes is not required, but most developers will find they simplify the task of building a DirectShow-based MSP for TAPI 3.0's new MSPI.

Familiarity with COM, ATL, DirectShow, and C++ is assumed. The reader must also know the general material in About the Media Service Provider (MSP) and in Media Service Provider Interface (MSPI).

ATL 2.1 is required for Windows 2000. Both ATL 2.1 and 3.0 will compile for Whistler.

MSP Base Class Libraries (available in the SDK):

Mspbase.lib

Mspid.lib

Rtutils.lib

Strmbase.lib

Tmuid.lib

Note Dynamic rather than static linking should be used.

MSP Base Class Header Files (available in the SDK):

Mspaddr.h

Mspbase.h

Mspcall.h

Msplog.h

Mspstrm.h

Mspterm.h

Mspthrd.h

Msptmac.h

Msptmvc.h

Msptrmvc.h

Msptrmac.h

Msptrmar.h

Msputils.h

MSP Base Class Source Files (available in the SDK Samples):

mspaddr.cpp

mspcall.cpp

msplog.cpp

mspstrm.cpp

mspterm.cpp

mspthrd.cpp

msptrmac.cpp

msptrmar.cpp

msptrmvc.cpp

msputils.cpp


Features Supported

  1. Implements an MSP that handles a single address per instance of the MSP. Multiple like addresses are handled by instantiating the MSP multiple times. This greatly simplifies the implementation of the MSP and the base classes.
  2. Implements all the MSPI interfaces, including ITMSPAddress, ITTerminalSupport, ITStreamControl, and ITStream.
  3. Implements ready-to-use static terminals for both audio and video.
  4. Implements generic terminal base classes. These terminal base classes are used by both the above-mentioned static terminal implementations and the implementations of dynamic terminals that are found in Termmgr.dll. The MSP can also use them to implement additional terminals.
  5. Uses the Terminal Manager to handle dynamic terminals. Creates dynamic terminals on a worker thread with a message pump (to free console applications from having to process window messages for video render terminals and to simplify synchronization issues).
  6. Supports calls that use a filter graph per stream.
  7. Implements handling of graph events.
  8. Uses the thread pooling APIs, in conjunction with a worker thread of its own, to handle events.
  9. Uses the tracing APIs of Windows 2000 (originally developed for the Routing project) along with additional logic to provide a flexible, generic logging mechanism that can simultaneously log to any combination of the following: a user or kernel-mode debugger; a separate console window with log messages separated by component; a log file.
  10. Runs free-threaded.


Features Not Supported

  • Dynamic graph handling will be implemented by the derived MSP, if it chooses to do so.
  • SubStreams will be implemented by the derived MSP, if it chooses to do so.
  • Private interfaces, such as participants, codec control, etc., will not be implemented by the base classes.
  • TSP-MSP communication will be implemented by the derived MSP.


General Design Goals

  1. Base classes have been kept simple, with members and methods introduced only when absolutely necessary.
  2. Simple inheritance. No multiple inheritance among classes, although multiple inheritance is used for the interfaces.
  3. Locking happens only in one direction to prevent deadlock. Methods on the call object that require the lock on the call might call methods on the stream that require the lock on the stream. However, methods on the stream that require the lock on the stream will never call a method on the call that requires a lock on the call.
  4. Refcounts are used to protect access. All callbacks posted to the thread pool hold refcounts. The refcount is canceled when the wait is canceled. The Address object has refcounts on Terminals. Call objects have refcounts on the Address and on Streams. Stream objects have refcounts on Calls and Terminals. The Terminals have refcounts on Streams. The circular refcounts break when the shutdown method on the Address and Call objects is called.


Using The TAPI 3.0 MSP Base Classes

These steps illustrate what a developer needs to do to implement an MSP using ATL 2.1 or 3.0 and the MSP base classes. See TAPI 3.0 MSP Base Classes for a list of libraries and headers. The following material assumes that the developer has a working understanding of ATL and COM, and has experience implementing COM DLLs using ATL.

  1. Create an IDL file for your MSP. This file defines a CLSID for your MSP. You must declare your MSP's "coclass" as implementing the ITMSPAddress interface, and declare this interface as the default interface on your class object. For the definition of ITMSPAddress, you will need to import the file "msp.idl". You will want to include your MSP's "coclass" in a type library for your MSP. If your MSP supports any private (custom) interfaces, define them here and include them in your type library. The following is an example IDL file as described above, without any custom interfaces:
    import "msp.idl";
[
      uuid(4DDB6D35-3BC1-11d2-86F2-006008B0E5D2),
      version(2.0),
      helpstring("Wave MSP 2.0 Type Library")
]
library WAVEMSPLib
{
importlib("stdole32.tlb");
importlib("stdole2.tlb");

[
uuid(4DDB6D36-3BC1-11d2-86F2-006008B0E5D2),
helpstring("Wave MSP Class")
]
coclass WaveMSP
{
[default] interface ITMSPAddress;
};
};
  2. Modify your TSP to advertise the CLSID of your MSP when Tapi3.dll asks for it. To do this, make sure that (1) your TSP can negotiate TAPI_VERSION3_0 or higher in the TSPI function lineNegotiateAPIVersion, (2) your TSP's LINEDEVCAPS structure has the LINEDEVCAPFLAGS_MSP flag set in the dwDevCapFlags member, and (3) your TSP returns your MSP's CLSID in the TSPI function TSPI_lineMSPIdentify. This should be the same CLSID that is specified in your IDL file; for example, the second "uuid" line in the example IDL file in the previous step.
  3. Link your MSP DLL with Mspbase.lib from the SDK.
  4. Include Mspbase.h from the SDK for MSP base class definitions.
  5. Implement your DLL exports (DllMain, etc.). Microsoft Visual C++ will generate these for you. In DllMain, on DLL_PROCESS_ATTACH and DLL_PROCESS_DETACH, respectively, use the MSPLOGREGISTER and MSPLOGDEREGISTER macros to enable up logging features for your DLL. Specify the name of your DLL in the MSPLOGREGISTER call.
  6. Use the LOG macro, defined in Msplog.h, to output trace messages in the same fashion as the base classes. Define the MSPLOG preprocessor symbol to include logging in your DLL; leave it undefined to build a DLL that does not have logging.
  7. Derive a class from CMSPAddress that implements addresses for your MSP. Declare a global ATL object map which tells ATL to create an instance of your address class when asked to CoCreate on the CLSID you specified in your IDL file. Also, derive your address class from ATL's CComCoClass template, and include a DECLARE_REGISTRY_RESOURCEID declaration in your address class. Construct a corresponding resource script and header file, just as you would do for any other ATL COM DLL.
  8. Implement the required CMSPAddress overrides for your address class. For MSPAddressAddRef and MSPAddressRelease, simply call the provided helper function templates. For GetCallMediaTypes, simply return a DWORD bitmap with all of your MSP's supported TAPIMEDIAMODEs ORed together. For CreateMSPCall and ShutdownMSPCall, you should be able to just return E_NOTIMPL and compile and link your MSP at this point. At this stage you may want to verify that you can register and instantiate your MSP from TAPI 3.0 applications (but not successfully create calls).
  9. Derive a class from CMSPCallMultiGraph to implement your MSP's call objects. You may want to derive from CMSPCallBase instead of CMSPCallMultiGraph if the filter-graph-per-stream model does not fit your requirements, but this will make your job harder (as of this writing, all MSPs to date have derived their call objects directly from CMSPCallMultiGraph). In your address object, implement CreateMSPCall and ShutdownMSPCall to create and shut down your specific type of call object using the provided helper function templates. In your call object, override CreateStreamObject to return E_NOTIMPL for now. Override MSPCallAddRef and MSPCallRelease in a manner identical to the corresponding address methods. Again, you should be able to compile and link your MSP; it should now be able to create and shut down calls (but the calls will not do any useful streaming).
  10. Derive a class from CMSPStream to implement your MSP's stream objects. In your call object, implement CreateStreamObject to create and initialize your stream object (typically by calling ATL's CreateInstance followed by ATL's _InternalQueryInterface for ITStream followed by calling Init on your stream object). lf you plan to support a fixed number of streams (this is common for MSPs which do not support modification of stream configurations by other endpoints on the call), override Init, CreateStream, and RemoveStream on your call object. (The call Init creates all of your streams initially, and CreateStream and RemoveStream simply return the appropriate TAPI error codes to prevent the application from creating or removing streams). Otherwise, override the call's Init method to create some initial default configuration of streams using the media types requested for the call. When creating any default stream objects in your call's Init method, simply use the InternalCreateStream helper method.
  11. Implement your stream object. The only required override is the get_Name method, which simply returns a friendly name for the stream. In addition, you will need to override several other methods. Exactly which methods to override depends on your implementation and when you decide to perform the various tasks involved in constructing and tearing down your filter graph. These tasks include creating the appropriate "transport" filters, codecs, etc., and inserting them and removing them from the filter graphs at the appropriate times. You will also have to use the ITTerminalControl interface on terminal objects to connect the selected terminals to your streams. You may want to override SelectTerminal and UnselectTerminal on your stream object to limit the terminal configurations that your streams will accept; limiting each stream to a single terminal will especially simplify construction of your filter graphs, but will sacrifice application functionality such as video preview. Depending on your implementation, you will place your graph construction, teardown, and terminal connection code in the StartStream, StopStream, PauseStream, Initialize, Shutdown, SelectTerminal, and UnselectTerminal methods, or in your own methods based on private TSP communication. Note that a stream with no terminals selected must still keep track of the desired graph state; a StartStream call followed by a SelectTerminal call on such a stream must result in commencement of streaming. You will have to override most of these methods to ensure that the correct construction, teardown, connection, and disconnection happens in each case depending on the state of the stream.
  12. Implement your TSP communication. Override CMSPAddress::ReceiveTSPAddressData and/or CMSPCallBase::ReceiveTSPCallData, and/or by calling PostEvent on your address object, or HandleStreamEvent on your call object (from either your call or stream objects).
  13. Use PostEvent on your address object, or HandleStreamEvent on your call object (from either your call or stream objects) to send call media events to the application via Tapi3.dll. You will typically do this on your stream object, in overridden methods including the ProcessGraphEvent, StopStream, StartStream, PauseStream, SelectTerminal, and UnselectTerminal methods, depending on how you implement your streams.
  14. Implement any desired private interfaces or substreams on your existing objects (address, call, and stream). Usually there are none. Note that when implementing your private interfaces you will have to specify the LIBID of your type library from your IDL file. This means that application programmers will have to use your MSP's type library when using your custom interfaces. The standard MSP interfaces, implemented in the MSP base classes, use Tapi3.dll's LIBID and are therefore accessible to all TAPI 3 applications.
  15. If you are implementing MSP-specific static or dynamic terminal objects or replacements for the default static terminals (this is not typical), you can use the provided terminal base classes to do so. You will have to override various methods on your address object to provide alternative or additional methods of creating terminal objects.
  16. Implement the IObjectSafety interface on your Address, Call, Stream, and Terminal objects. If you want to use Dispatch Mapper to query for interfaces on your MSP objects, you will need to mark your objects as safe for scripting on these interfaces. You should do this by implementing the IObjectSafety interface on your object. Deriving from CMSPObjectSafetyImpl (a helper class provided in Msputils.h) and adding IObjectSafety to your class's ATL COM_MAP will make your objects safe for scripting on all the interfaces they expose. Note that using Dispatch Mapper on MSP objects could be implicit. MSP Address and MSP Call are aggregated by TAPI Address and TAPI Call objects. If Dispatch Mapper is used on the TAPI objects to query for the interfaces exposed by the aggregated MSP objects, the aggregated MSP objects will be queried for safety of the requested interfaces.


How to Enable Debug Tracing/Logging for Derived MSPs

First, make sure that the implementation of the derived MSP has followed the guidelines in the previous section with regard to debug tracing (defining the preprocessor symbol MSPLOG, registering for tracing during DllMain, and using the LOG macro for tracing). Find out what name the MSP uses when registering for tracing (this should usually be the DLL's name; it is referred to below as
"<dll name>"). To enable tracing, use a registry editor ("Regedit.exe" or "Regedt32.exe") to locate the key "HKEY_LOCAL_MACHINE\Software\Microsoft\Tracing" and do the following. Note that all of the values mentioned below, except the EnableDebuggerTracing value, should be created automatically after running your MSP for the first time.

  • To enable tracing to user and kernel mode debuggers, set the DWORD value <dll name>\EnableDebuggerTracing to 1. Optionally, use the DWORD value <dll name>\ConsoleTracing Mask to enable or disable various levels of trace output (the default is 0xFFFF0000, which enables all trace levels).
  • To enable tracing to a file, set the DWORD value <dll name>\EnableFileTracing to 1. Optionally, use the string value <dll name>\FileDirectory to adjust the location of the log file. Optionally, use the DWORD value <dll name>\FileTracingMask to enable or disable various levels of trace output (the default is 0xFFFF0000, which enables all trace levels).
  • To enable tracing to a separate console window, separated by DLL, set the DWORD value EnableConsoleTracing to 1, AND ALSO set the DWORD value <dll name>\EnableConsoleTracing to 1. Optionally, use the DWORD value <dll name>\ConsoleTracing Mask to enable or disable various levels of trace output (the default is 0xFFFF0000, which enables all trace levels).


TAPI 3.0 MSP Base Classes Reference

The following material provides details on the Media Service Provider base classes.

Media service provider base classes (alphabetical order) | Description
CAudioCaptureTerminal | Derived from CSingleFilterTerminal and implements a static audio capture terminal for wave devices using the DirectShow wavein filter. Defined in MSPtmac.h.
CAudioRenderTerminal | Derived from CSingleFilterTerminal and implements a static audio render terminal for wave devices using the DirectShow waveout filter. Defined in MSPtrmar.h.
CBaseTerminal | A terminal base class applicable to both static and dynamic terminals. It is completely generic, so any terminal implementation can derive from this class directly or indirectly. Defined in MSPterm.h
CMSPAddress | Implements the MSP address object and supports the ITMSPAddress interface. Defined in MSPaddr.h.
CMSPArray | A template that implements a smart array that will grow on demand. Defined in MSPutils.h.
CMSPCallBase | Provides a generic implementation of the call object and supports the ITStreamControl interface. Defined in MSPcall.h.
CMSPCallMultiGraph | Defines a call that uses a filter graph for each stream. Defined in MSPcall.h.
CMSPStream | Exposes methods that allow an application to start, pause, or stop a substream, and to select or unselect terminals. Defined in MSPstrm.h.
CMSPThread | Implements the MSP's worker thread. Defined in MSPthrd.h.
CSingleFilterTerminal | An additional terminal base class applicable to both static and dynamic terminals. Makes implementation more specific by assuming the terminal has a single DirectShow filter. Defined in MSPterm.h.
CVideoCaptureTerminal | Derived from CSingleFilterTerminal and implements a static video capture terminal using a single DirectShow filter. Defined in MSPtmvc.h.


CMSPArray

The CMSPArray template implements a smart array that will grow on demand. It is designed to hold small arrays with simple data types. It doesn't have a critical section. Its only dependencies are realloc and memmove. It is used internally to keep lists of object pointers. It is similar to ATL's CSimpleArray implementation, but it is more efficient for initial allocations.

This template is defined in MSPutils.h.


CMSPAddress

The CMSPAddress class implements the MSP address object and supports the ITMSPAddress interface. This class is defined in MSPaddr.h. The following documents the class.

CMSPAddress Type Definitions
CMSPAddress Members
CMSPAddress MSPI Methods Implemented
CMSPAddress Public Methods
CMSPAddress Internal Helper Methods
CMSPAddress Pure Virtual Methods
CMSPAddress Template Helper Methods


CMSPAddress Type Definitions

MSPEVENTITEM


MSPEVENTITEM

The MSPEVENTITEM structure contains link pointers and event types for MSP events.

typedef struct
{
  LIST_ENTRY Link;
  MSP_EVENT_INFO MSPEventInfo;
} MSPEVENTITEM, *PMSPEVENTITEM;

Members

Link
Doubly-linked list. Part of Windows 2000 run-time routines that are callable by both kernel mode code in the executive and user mode code in various subsystems. See Ntrtl.h or search the Platform SDK for details.
MSPEventInfo
The MSP_EVENT_INFO structure contains information concerning an event.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Mspaddr.h.


CMSPAddress Members

Member types | Name | Description
Iunknown | *m_pFTM | Pointer to the free threaded marshaller.
HANDLE | m_htEvent | Handle to Tapi3.dll's event, which is used to notify TAPI that the MSP wants to send data to it.
LIST_ENTRY | m_EventList | List of events.
CMSPCritSection | m_EventDataLock | The lock that protects the data related to event handling with TAPI.
ITTerminalManager | *m_pITTerminalManager | The pointer to the Terminal Manager object.
CMSPArray <ITTerminal *> | m_Terminals | The list of static terminals that can be used on the address.
BOOL | m_fTerminalsUpToDate | This flag is TRUE if the terminal list is up to date.
CMSPCritSection | m_TerminalDataLock | The lock that protects the terminal-related data members.


CMSPAddress MSPI Methods Implemented

The following are standard MSPI methods that all MSPs must implement. Primary documentation for these methods exists in the Media Service Provider Interface (MSPI) Reference section.

CMSPAddress methods | Description
Initialize | (Interface ITMSPAddress) Called by TAPI3 when this MSP is first created.
ShutDown | (Interface ITMSPAddress) Called by TAPI3 when this address is not in use any more.
ReceiveTSPData | (Interface ITMSPAddress) Called by TAPI3 when the TSP sends data to this MSP address object.
GetEvent | (Interface ITMSPAddress) Called by TAPI3 to get detailed information about an event.
get_StaticTerminals | (Interface ITTerminalSupport) OLE Automation wrapper for the helper function GetStaticTerminals.
EnumerateStaticTerminals | (Interface ITTerminalSupport) Enumeration wrapper for the helper function GetStaticTerminals.
get_DynamicTerminalClasses | (Interface ITTerminalSupport) OLE Automation wrapper for the helper function GetDynamicTerminalClasses.
EnumerateDynamicTerminalClasses | (Interface ITTerminalSupport) Enumeration wrapper for the helper function GetDynamicTerminalClasses.
CreateTerminal | (Interface ITTerminalSupport) This method is called by the application to create a dynamic terminal. It schedules a work item on the MSP's worker thread, which, when executed, asks the Terminal Manager to create a dynamic terminal. The derived class can override this method to have its own way of creating a dynamic terminal.
GetDefaultStaticTerminal | (Interface ITTerminalSupport) This method is called by the application to get the default static terminal for a specified type and direction. It updates the default terminal list (if needed) and returns the interface pointer. The derived class can override this method to have its own way of deciding which terminal is the default. Locks the terminal lists.


CMSPAddress Public Methods

CMSPAddress public methods | Description
IsValidSetOfMediaTypes | Checks to see if the specified media type is nonzero and is in the specified mask.
PostEvent | Called by the MSPCall to post an event to TAPI3.


CMSPAddress::IsValidSetOfMediaTypes

This method checks to see if the specified media type is nonzero and is in the specified mask. Your MSP can override this if it needs to do atypically complex checks on specific combinations of media types (e.g., can never have more than one media type on a call, can have video with audio but not video alone, etc.). The default implementation accepts any nonempty set of media types that is a subset of the set of types in the mask.

virtual BOOL IsValidSetOfMediaTypes(
  DWORD dwMediaType,
  DWORD dwMask
);

Parameters

dwMediaType
[in] Media type to check.
dwMask
[in] Media types mask indicating types that can be handled.

See Also

CMSPAddress


CMSPAddress::PostEvent

This method is called by the MSPCall to post an event to TAPI3. This method puts the event at the end of the event list and signals TAPI3. Locks the event list.

virtual HRESULT PostEvent(
  MSPEVENTITEM *EventItem
);

Parameters

EventItem
[in] Pointer to the MSPEVENTITEM structure, which contains the event information.

See Also

CMSPAddress


CMSPAddress Internal Helper Methods

CMSPAddress internal helper methods | Description
GetStaticTerminals | Called by get_StaticTerminals and EnumerateStaticTerminals to get an array of static terminals that can be used on this address.
GetDynamicTerminalClasses | Called by get_DynamicTerminalClasses and EnumerateDynamicTerminalClasses to get an array of dynamic terminal classes that can be used on this address.
UpdateTerminalList | Populates the MSP's list of static terminals.
ReceiveTSPAddressData | Called when a TSP data message is intended to be processed by the address rather than by a specific call.

See Also

CMSPAddress


CMSPAddress::GetStaticTerminals

This method is called by our wrapper methods (get_StaticTerminals and EnumerateStaticTerminals) to get an array of static terminals that can be used on this address. This method updates the address' internal list of terminals by calling UpdateTerminalList if the list is not up to date. If the ppTerminals parameter is NULL or the *pdwNumTerminals parameter is not large enough to hold all the terminal pointers, this method simply returns (as *pdwNumTerminals) the number of terminals available. If ppTerminals is non-NULL and *pdwNumTerminals is large enough, it AddRefs each terminal pointer and places the array of terminal pointers in *ppTerminals, setting *pdwNumTerminals to the number of terminal pointers returned. If the derived MSP wants to change the set of terminals returned, it will probably override UpdateTerminalList rather than overriding this method.

virtual HRESULT GetStaticTerminals(
  DWORD *pdwNumTerminals,
  ITTerminal **ppTerminals
);

Parameters

pdwNumTerminals
[out] Pointer to number of static terminals.
ppTerminals
[out] Pointer to array of ITTerminal interfaces.

See Also

CMSPAddress


CMSPAddress::GetDynamicTerminalClasses

This method is called by our wrapper methods (see above) to get an array of dynamic terminal classes that can be used on this address. The semantics of the arguments are the same as for GetStaticTerminals. This method simply asks the Terminal Manager for the terminal classes. MSPs that implement additional, custom types of dynamic terminals, or that want to disallow the use of certain dynamic terminal classes from the Terminal Manager, would want to override this method.

virtual HRESULT GetDynamicTerminalClasses(
  DWORD *pdwNumClasses,
  IID *pTerminalClasses
);

Parameters

pdwNumClasses
[out] Pointer to number of dynamic terminals.
pTerminalClasses
[out] Pointer to array of ITTerminal interfaces.

See Also

CMSPAddress


CMSPAddress::UpdateTerminalList

This method populates the MSP's list of static terminals. It assumes that we have no static terminals available and it is always called in situations where this is true. This method uses DirectShow's "devenum" component and a static list of categories to discover monikers for static terminals. It uses the static CreateTerminal methods on each type of terminal (see below) to actually create the terminals, possibly failing if the moniker in question is not acceptable (see below). For each successfully created terminal, it adds the terminal to the address' list. When this process is complete, devenum is released. An MSP that uses different static terminals than the ones created or that needs to use additional static terminals must override this method. The categories currently used here are CLSID_CWaveInClassManager, CLSID_CWaveOutClassManager, and CLSID_CVidCapClassManager. The method does not use categories that correspond to media types that the derived MSP does not support (this is checked automatically in the base class).

virtual HRESULT UpdateTerminalList();

Parameters

This method has no parameters.

See Also

CMSPAddress


CMSPAddress::ReceiveTSPAddressData

This method is called when a TSP data message is intended to be processed by the address rather than by a specific call. Your MSP must override this method if it wants to handle any per-address TSP messages.

virtual HRESULT ReceiveTSPAddressData(
  PBYTE pBuffer,
  DWORD dwSize
);

Parameters

pBuffer
[in, out] Pointer to buffer.
dwSize
[out] Pointer to number of characters in the buffer.


CMSPAddress Pure Virtual Methods

These methods must be overridden by derived classes.

CMSPAddress pure virtual methods | Description
MSPAddressAddRef | Private AddRef method for the address.
MSPAddressRelease | Private Release method for the address.
CreateMSPCall | Called by TAPI to create a call object. The implementation in the derived class should simply call the CreateMSPCallHelper function.
ShutdownMSPCall | Called by TAPI to shut down a call object. The implementation in the derived class should simply call the ShutdownMSPCallHelper function.
GetCallMediaTypes | Gets media types supported by the MSP.

See Also

CMSPAddress


CMSPAddress::MSPAddressAddRef

This is the private AddRef method for the address. MSP objects that keep references to the address must call this method instead of the normal COM AddRef method so that the reference is kept on the MSP address object instead of on the aggregate TAPI address object. This is crucial to ensure correct object lifetimes. A template helper function, MSPAddRefHelper, is provided to help the derived MSP implement this method. All the derived MSP has to do in its implementation of this method is call "MSPAddRefHelper(this)". This is needed simply to provide the type of the derived class to the template helper function.

virtual ULONG MSPAddressAddRef() = 0;

Parameters

This method has no parameters.

See Also

CMSPAddress


CMSPAddress::MSPAddressRelease

This is the private Release method for the address. MSP objects that keep references to the address must call this method instead of the normal COM Release method so that the reference is kept on the MSP address object instead of on the aggregate TAPI address object. This is crucial to ensure correct object lifetimes. A template helper function, MSPReleaseHelper, is provided to help the derived MSP implement this method. All the derived MSP has to do in its implementation of this method is call "MSPReleaseHelper(this)". This is needed simply to provide the type of the derived class to the template helper function.

virtual ULONG MSPAddressRelease() = 0;

Parameters

This method has no parameters.

See Also

CMSPAddress


CMSPAddress::GetCallMediaTypes

This method gets media types supported by the MSP. The derived class must override this method to indicate the media types supported. The relevant TAPIMEDIATYPE constants should be ORed together and returned.

virtual DWORD GetCallMediaTypes() = 0;

Parameters

This method has no parameters.

See Also

CMSPAddress


CMSPAddress Template Helper Methods

These methods are not in the class.

CMSPAddress template helper methods | Description
CreateMSPCallHelper | Called in the derived class' implementation of CreateMSPCall.
ShutdownMSPCallHelper | Called in the derived class' implementation of ShutdownMSPCall.

See Also

CMSPAddress


CMSPAddress::CreateMSPCallHelper

This helper template function is called in the derived class' implementation of CreateMSPCall. It checks all of the arguments for validity, including the media type argument (via the address object method IsValidSetOfMediaTypes; see above). It sets up the aggregation between the MSP call object and the TAPI call object using the CComAggObject ATL class template. It then calls the Init method on the MSP call object.

HRESULT CreateMSPCallHelper(
  CMSPAddress *pCMSPAddress,
  MSP_HANDLE htCall,
  DWORD dwReserved,
  DWORD dwMediaType,
  IUnknown *pOuterUnknown,
  IUnknown **ppMSPCall,
  T **ppCMSPCall
);

Parameters

pCMSPAddress
Pointer to CMSPAddress interface for call.
htCall
Handle for MSP.
dwReserved
Reserved parameter, not currently used.
dwMediaType
Media types desired for call.
pOuterUnknown
Pointer to IUnknown interface for TAPI call object.
ppMSPCall
Pointer to IUnknown interface for MSP call object.
ppCMSPCall
Pointer to templated MSP call class, type implementation dependent.

See also

CreateMSPCall, CMSPAddress


CMSPAddress::ShutdownMSPCallHelper

This helper template function is called in the derived class' implementation of ShutdownMSPCall. It manipulates the passed-in aggregated TAPI call object Unknown pointer via dynamic casts to obtain a pointer to the inner MSP call object, and then calls the Shutdown method on the MSP call object (see below).

template <class T>
HRESULT ShutdownMSPCallHelper(
  IUnknown *pUnknown,
  T **ppCMSPCall
);

Parameters

pUnknown
Pointer to IUnknown on aggregated TAPI call object.
ppCMSPCall
Pointer to templated MSP call class, type implementation dependent.

See Also

CMSPAddress


CMSPCallBase

The CMSPCallBase class provides a generic implementation of the call object. It supports the ITStreamControl interface. It serves as a simple base class that maintains the stream list. This class is defined in MSPcall.h.

CMSPCallBase Members
CMSPCallBase MSPI Methods Implemented
CMSPCallBase Public Methods, Called By MSPAddress Object
CMSPCallBase Public Methods, Called by MSPStream Object
CMSPCallBase Pure Virtual Methods


CMSPCallBase Members

Member type | Name | Description
IUnknown | *m_pFTM | Pointer to the free threaded marshaller.
CMSPAddress* | *m_pMSPAddress | The pointer to MSP address object. It is used to get the default terminals if the application doesn't select any. It also carries a refcount (via MSPAddressAddRef, not AddRef) so that the aggregated address will not go away while the call is still alive, but TAPI 3.0's address is not AddRef'ed.
MSP_HANDLE | *m_htCall | The handle to TAPI3's call. Used to fire call events.
DWORD | m_dwMediaType | Bitmask of the media types on this call.
CMSPArray <ITStream *> | m_Streams | The list of stream objects in the call.
CMSPCritSection | m_lock | The lock that protects the stream lists.

See Also

CMSPCallBase


CMSPCallBase MSPI Methods Implemented

CMSPCallBase MSPI helper methods | Description
CreateStream | Creates the media stream for a new call. Acquires the lock in the function.
EnumerateStreams | Enumerates streams currently available. Acquires the lock in the function.
get_Streams | Creates a collection of streams currently available. Provided for Automation client applications, such as those written in Microsoft Visual Basic. Acquires the lock in the function.

See Also

CMSPCallBase


CMSPCallBase Public Methods, Called By MSPAddress Object

CMSPCallBase public methods | Description
ReceiveTSPCallData | Called by the MSP address object's ReceiveTSPData method to dispatch TSP data to the correct call.

See Also

CMSPCallBase


CMSPCallBase::ReceiveTSPCallData

This method is called by the MSP address object's ReceiveTSPData method to dispatch TSP data to the correct call. The call object should override this method to handle the TSP data according to whatever semantics have been defined for communication between this particular MSP and its corresponding TSP. The default implementation simply returns S_OK, which is sufficient for an MSP that does not handle any per-call TSP data.

virtual HRESULT ReceiveTSPCallData(
  PBYTE pBuffer,
  DWORD dwSize
);

Parameters

pBuffer
Pointer to buffer containing TSP data.
dwSize
Size in bytes of pBuffer.

See Also

CMSPCallBase


CMSPCallBase Public Methods, Called by MSPStream Object

CMSPCallBase public methods | Description
HandleStreamEvent | Called by a stream to send an event to TAPI.

See Also

CMSPCallBase


CMSPCallBase::HandleStreamEvent

This method is called by a stream to send an event to TAPI. It fills in the call handle in the event info structure and then calls the PostEvent method on the MSP address object. (Note that this way, events generated on the streams "flow" toward the address object via the call object, with more information filled in at each step. This reduces the amount of state that must be kept in the MSP call and MSP stream objects.)

virtual HRESULT HandleStreamEvent(
  MSPEVENTITEM *EventItem
) const;

Parameters

EventItem
Pointer to MSPEVENTITEM, a struct containing a linked list of MSP_EVENT_INFO structs.

See Also

CMSPCallBase


CMSPCallBase Pure Virtual Methods

These methods must be overridden by derived classes.

CMSPCallBase pure virtual methods | Description
MSPCallAddRef | Private AddRef method for the call object.
MSPCallRelease | Private Release method for the call object.
Init | Called by the MSP address object (in the method CreateMSPCall) to initialize the MSP call object.
ShutDown | Called by the MSP address object to shut down the call..
InternalCreateStream | Called by CreateStream to create a stream object.
CreateStreamObject | Called by InternalCreateStream to create a stream object.
RemoveStream | Called by the application to remove a stream from the call

See Also

CMSPCallBase


CMSPCallBase::MSPCallAddRef

This is the private AddRef method for the call object. MSP objects that keep references to the call object must call this method instead of the normal COM AddRef method so that the reference is kept on the MSP call object instead of on the aggregate TAPI call object. This is crucial to ensure correct object lifetimes. A template helper function, MSPAddRefHelper, is provided to help the derived MSP implement this method. All the derived MSP has to do in its implementation of this method is call "MSPAddRefHelper(this)". This is needed simply to provide the type of the derived class to the template helper function.

virtual ULONG MSPCallAddRef() = 0;

Parameters

This method has no parameters.

See Also

CMSPCallBase


CMSPCallBase::MSPCallRelease

This is the private Release method for the call object. MSP objects that keep references to the call object must call this method instead of the normal COM Release method so that the reference is kept on the MSP call object instead of on the aggregate TAPI call object. This is crucial to ensure correct object lifetimes. A template helper function, MSPReleaseHelper, is provided to help the derived MSP implement this method. All the derived MSP has to do in its implementation of this method is call "MSPReleaseHelper(this)". This is needed simply to provide the type of the derived class to the template helper function.

virtual ULONG MSPCallRelease() = 0;

Parameters

This method has no parameters.

See Also

CMSPCallBase


CMSPCallBase::Init

This method is called by the MSP address object (in the method CreateMSPCall) to initialize the MSP call object. The derived class should initialize its members using the passed-in information.

virtual HRESULT Init(
  CMSPAddress *pMSPAddress,
  MSP_HANDLE htCall,
  DWORD dwReserved,
  DWORD dwMediaType,
) = 0;

Parameters

pMSPAddress
Pointer to MSP call object to be initialized.
htCall
The MSP handle for the call.
dwReserved
Reserved.
dwMediaType
Media type or types of call.

See Also

CMSPCallBase, CMSPCallMultiGraph::Init, CreateMSPCall


CMSPCallBase::ShutDown

This method is called by the MSPAddress object (in the method ShutdownMSPCall) to shut down the call. The derived class implementation should shut down all the streams on the call. (See also CMSPCallMultiGraph::ShutDown below.)

virtual HRESULT ShutDown() = 0;

Parameters

This method has no parameters.

See Also

CMSPCallBase


CMSPCallBase::InternalCreateStream

This method is called by CreateStream to create a stream object (the caller does the argument checking). It should create and initialize the stream object (using CreateStreamObject).

virtual HRESULT InternalCreateStream(
  DWORD dwMediaType,
  TERMINAL_DIRECTION Direction,
  ITStream **ppStream
) = 0;

Parameters

dwMediaType
Media type or types of call.
Direction
Indicates terminal direction.
ppStream
Pointer to ITStream object interface.

See Also

CMSPCallBase, CreateStream, CreateStreamObject, CMSPCallMultiGraph::InternalCreateStream, ITStream


CMSPCallBase::CreateStreamObject

This method is called by InternalCreateStream. The derived class should CreateInstance on its stream object, do an ATL _InternalQueryInterface to obtain an ITStream pointer from the stream object, and call the stream object's Init method (on the stream object pointer, not the ITStream pointer).

virtual HRESULT CreateStreamObject(
  DWORD dwMediaType,
  TERMINAL_DIRECTION Direction,
  IMediaEvent *pGraph,
  ITStream **ppStream
) = 0;

Parameters

dwMediaType
Media type of stream to be created.
Direction
Direction of stream.
pGraph
Pointer to DirectShow IMediaEvent interface.
ppStream
Pointer to ITStream interface.

See Also

CMSPCallBase


CMSPCallBase::RemoveStream

(Interface ITStreamControl) This method is called by the application to remove a stream from the call. Derived MSP call objects that do not want to allow applications to remove streams should override this to simply return TAPI_E_NOTSUPPORTED. (This is a good simplification strategy for many MSPs.) Derived call objects that do support removal of streams by the application should override this method to remove the stream object from the call object's list of streams and release the call's references to the stream. (See below for the CMSPCallMultiGraph implementation.)

virtual HRESULT RemoveStream(
  ITStream *pStream
) = 0;

Parameters

pStream
Pointer to ITStream interface to be removed.

See Also

CMSPCallBase


CMSPCallMultiGraph

Derived from CMSPCallBase, this class defines a call that uses a filter graph for each stream. This extra increased specificity allows this class to implement more of the call's functionality than CMSPCallBase. Defined in MSPcall.h.

CMSPCallMultiGraph Type Definitions
CMSPCallMultiGraph Members
CMSPCallMultiGraph MSPI Methods Implemented
CMSPCallMultiGraph Public Methods, Called by MSPAddress Object
CMSPCallMultiGraph Public Methods, Called by Thread Pool
CMSPCallMultiGraph Overriden CComObject Methods
CMSPCallMultiGraph Protected Helper Methods

See Also

CMSPCallBase


CMSPCallMultiGraph Type Definitions

MSPSTREAMCONTEXT

THREADPOOLWAITBLOCK

See Also

CMSPCallMultiGraph


MSPSTREAMCONTEXT

The MSPSTREAMCONTEXT structure contains the key interface pointers required to handle a media event.

typedef struct
{
  CMSPCallMultiGraph *    pMSPCall;
  ITStream           *    pITStream;
  IMediaEvent        *    pIMediaEvent;
} MSPSTREAMCONTEXT, *PMSPSTREAMCONTEXT;

Members

pMSPCall
Pointer to CMSPCallMultiGraph interface for a call stream.
pITStream
Pointer to ITStream interface for the call.
pIMediaEvent
Pointer to DirectShow IMediaEvent interface.

See Also

CMSPCallMultiGraph


THREADPOOLWAITBLOCK

A wait block stores information about a wait registered to the thread pool. It includes the wait handles returned by the RegisterWaitForSingleObject call and a pointer to the context structure. Each block in the array is for a graph in one of the stream objects. The offset of a block in this array is the same as the offset of the stream that owns the graph.

typedef struct _THREADPOOLWAITBLOCK
{
  HANDLE              hWaitHandle;
  MSPSTREAMCONTEXT *  pContext;
  BOOL operator == (struct _THREADPOOLWAITBLOCK &t)
  {
      return ((hWaitHandle == t.hWaitHandle)
          && (pContext == t.pContext));
  }
} THREADPOOLWAITBLOCK, *PTHREADPOOLWAITBLOCK;

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph Members

CMSPArray <THREADPOOLWAITBLOCK>     m_ThreadPoolWaitBlocks;

The wait blocks store the information about the wait registered to the thread pool. It includes the wait handles returned by the RegisterWaitForSingleObject call and a pointer to the context structure. Each block in the array is for a graph in one of the stream objects. The offset of a block in this array is the same as the offset of the stream that owns the graph.


CMSPCallMultiGraph MSPI Methods Implemented

CMSPCallMultiGraph MSPI methods | Description
RemoveStream | Called by the application to remove a stream from the call.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::RemoveStream

(Interface ITStreamControl) This method is called by the application to remove a stream from the call. Derived MSP call objects that do not want to allow applications to remove streams should override this to simply return TAPI_E_NOTSUPPORTED. (This is a good simplification strategy for many MSPs.) The default implementation removes the stream object from the call object's list of streams and releases the call's references to the stream.

virtual HRESULT RemoveStream(
  ITStream *ppStream
);

Parameters

ppStream
Pointer to ITStream interface for stream to be removed from the call.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph Public Methods, Called by MSPAddress Object

CMSPCallMultiGraph public methods | Description
Init | Called by the MSP address object (in the method CreateMSPCall) to initialize the MSP call object.
ShutDown | Called by the MSP address object (in the method ShutdownMSPCall) to shut down the MSP call object.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::Init

This method is called by the MSP address object (in the method CreateMSPCall) to initialize the MSP call object. The CMSPCallMultiGraph implementation initializes its members using the passed-in information. It calls MSPAddressAddRef on the MSP address object. Derived MSPs will want to override this method and call it in the overridden method; the overridden method should create the default streams based on the passed-in media types.

virtual HRESULT Init(
  CMSPAddress *pMSPAddress,
  MSP_HANDLE htCall,
  DWORD dwReserved,
  DWORD dwMediaType
);

Parameters

pMSPAddress
Pointer to CMSPAddress for call being initialized.
htCall
The MSP's handle for the call being initialized
dwReserved
Reserved parameter.
dwMediaType
Media type or types of call.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::ShutDown

This method is called by the MSP address object (in the method ShutdownMSPCall) to shut down the MSP call object. Cancels the thread pool waits on the call's graph events. Releases the references on all the stream objects. Calls the shutdown method on all the stream objects. Acquires the lock in the function.

virtual HRESULT ShutDown();

Parameters

This function has no parameters.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph Public Methods, Called by Thread Pool

CMSPCallMultiGraph public methods | Description
DispatchGraphEvent | Called when the filter graph signals an event.
HandleGraphEvent | Called by the DispatchGraphEvent static method. Queues ProcessGraphEvent on the main MSP worker thread.
ProcessGraphEvent | Allows the MSP call object instance to handle the filter graph event.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph_DispatchGraphEvent

Platform SDK: TAPI

DispatchGraphEvent

This is a static method posted to the RegisterWaitForSingleObject function during initialization. This function is called when the filter graph signals the event. The pContext parameter is a pointer to the MSPSTREAMCONTEXT structure. The pointers in the structure carry ref counts. The implementation of this method simply casts the pContext argument to type MSPSTREAMCONTEXT *, and then calls HandleGraphEvent on the MSP call object whose pointer appears in the structure.

static VOID NTAPI DispatchGraphEvent(
  VOID *pContext,
  BOOLEAN bFlag
);

Parameters

pContext
Contains pointer to MSPSTREAMCONTEXT structure.
bFlag
Not used. Required for RegisterWaitForSingleObject. Set TRUE if wait times out, but time-out in CMSPCallMultiGraph::RegisterWaitEvent is set to INFINITE.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::HandleGraphEvent

This method is called by the DispatchGraphEvent static method to let the call object instance handle the event. It asks the filter graph for the event code and parameters, and queues an asynchronous work item on the global worker thread object, which will result in the AsyncMultiGraphEvent function (as defined in MSPCall.h) being executed on the worker thread. This is to allow the thread pool thread to return as quickly as possible, preventing an event storm from DirectShow's manual reset event.

virtual VOID HandleGraphEvent(
  MSPSTREAMCONTEXT *pContext
);

Parameters

pContext
Contains pointer to MSPSTREAMCONTEXT structure.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::ProcessGraphEvent

The AsyncMultiGraphEvent callback function (as defined in MSPCall.h) is called on the MSP worker thread. It calls this method to let the call object instance handle the event, and then releases the call object and stream object references in its context structure. This method finds the indicated stream and dispatches the call to the ProcessGraphEvent method on the appropriate Stream object.

virtual HRESULT ProcessGraphEvent(
  ITStream *pITStream,
  long lEventCode,
  long lParam1,
  long lParam2
);

Parameters

pITStream
Pointer to ITStream interface.
lEventCode
Filled in by filter graph. Implementation dependent.
lParam1
Filled in by filter graph. Implementation dependent.
lParam2
Filled in by filter graph. Implementation dependent.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph Overriden CComObject Methods

CMSPCallMultiGraph Overriden CComObject methods | Description
FinalRelease | Releases the call object's reference to the address object.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::FinalRelease

Releases the call object's reference to the address object. This is postponed to FinalRelease in case the stream objects hold references on the call object during the shutdown process.

virtual void FinalRelease();

Parameters

This method has no parameters.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph Protected Helper Methods

CMSPCallMultiGraph protected helper methods | Description
RegisterWaitEvent | Adds a wait event to the thread pool.
UnregisterWaitEvent | Removes a wait event from the thread pool.
InternalCreateStream | Called by CreateStream to create a stream object.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::RegisterWaitEvent

This method should be called only within a critical section on the call object. It allocates a thread pool context block, fills in the fields, increments the reference counts, and posts the block to the thread pool by calling the Win32 function RegisterWaitForSingleObject. Saves the wait handle returned for use in UnregisterWaitEvent. Saves the wait block in the list of wait blocks.

HRESULT RegisterWaitEvent(
  IMediaEvent *pIMediaMedia,
  ITStream *pITStream
);

Parameters

pIMediaMedia
Pointer to DirectShow IMediaEvent interface.
pITStream
Pointer to ITStream interface.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::UnregisterWaitEvent

Calls the Win32 function UnregisterWait to tell the thread pool to stop waiting on the handle indicated by the wait block at the given index. Releases the refcounts in the wait block and frees the wait block. Removes the wait block from the list of wait blocks.

HRESULT UnregisterWaitEvent(
  int index
);

Parameters

index
Index on appropriate item in the array of THREADPOOLWAITBLOCK structures.

See Also

CMSPCallMultiGraph


CMSPCallMultiGraph::InternalCreateStream

This method is called by CreateStream to create a stream object (the caller does the argument checking). It creates and initializes the stream object (using CreateStreamObject). It uses CoCreateInstance to create a filter graph for the stream. It calls RegisterWaitEvent to start waiting for events on the filter graph. It adds the stream into the call object's list of stream objects. It addrefs the stream pointer and returns it.

virtual HRESULT InternalCreateStream(
  DWORD dwMediaType,
  TERMINAL_DIRECTION Direction,
  ITStream **ppStream
);

Parameters

dwMediaType
Descriptor of media type for stream.
Direction
Descriptor of terminal direction.
ppStream
Pointer to array of ITStream interfaces.

See Also

CMSPCallMultiGraph


CMSPStream

The CMSPStream class exposes methods that allow an application to start, pause, or stop a substream, and to select or unselect terminals. Defined in MSPstrm.h.

CMSPStream Type Definitions
CMSPStream Members
CMSPStream MSPI Methods Implemented
CMSPStream Public Methods, Called by MSPCall Object
CMSPStream Overriden CComObject Methods
CMSPStream Pure Virtual Methods


CMSPStream Type Definitions

The following definitions provide a set of stream states that may be useful to the derived class, although their use is not required. Derived classes can conveniently extend the set of available states simply by defining additional values.

#define STRM_INITIAL            0x00000000
#define STRM_TERMINALSELECTED   0x00000001
#define STRM_CONFIGURED         0x00000002
#define STRM_RUNNING            0x00000004
#define STRM_PAUSED             0x00000008
#define STRM_STOPPED            0x00000010

See Also

CMSPStream


CMSPStream Members

Member type | Name | Description
IUnknown | *m_pFTM | Pointer to the free threaded marshaller.
DWORD | m_dwState | The current state of the stream.
HANDLE | m_hAddress | The address on which this stream is being used.
DWORD | m_dwMediaType | The media type of this stream (audio, video, etc.).
TERMINAL_DIRECTION | m_Direction | The direction of this stream (incoming or outgoing).
CMSPCallBase | *m_pMSPCall | Pointer to the call object.
IGraphBuilder | *m_pIGraphBuilder | Pointer to graph object interfaces.
IMediaControl | *m_pIMediaControl | Pointer to the media control interface.
CMSPArray <ITTerminal *> | m_Terminals | The list of terminals on the stream.
CMSPCritSection | m_lock | The lock that protects the stream object. The stream object should never acquire the lock and then call an MSPCall method that might lock.

See Also

CMSPStream


CMSPStream MSPI Methods Implemented

CMSPStream MSPI methods | Description
get_MediaType | Gets the stream's media type.
get_Direction | Gets the stream's terminal direction.
SelectTerminal | Selects an ITTerminal object onto the stream. Acquires the lock in the function. This base class method only knows about maintaining the list of terminals; it is expected that the derived class will override this method to provide additional functionality (such as stopping and restarting the stream if a terminal is selected while the stream is running). The base class implementation checks if the terminal pointer points to valid memory, gets the ITTerminalControl interface from the terminal, retrieves the address handle from the terminal and checks if it matches the MSP's address handle, checks if the terminal already exists in the stream's list, adds the terminal to the stream's list of terminals, and AddRefs it. If any of the tests fail, it returns TAPI_E_INVALIDTERMINAL.
UnselectTerminal | Unselects the terminal from the stream. Acquires the lock in the function. Finds the terminal in the stream's list of terminals, removes it from the list, and releases it. If the terminal is not found, it returns TAPI_E_INVALIDTERMINAL.
EnumerateTerminals | Enumerates terminals selected on the stream.It is a snapshot of the terminals at this point. Acquires the lock in the function.
get_Terminals | Creates a collection of terminals associated with the current stream. Provided for Automation client applications, such as those written in Microsoft Visual Basic. It is a snapshot of the terminals at this point. Acquires the lock in the function.
StartStream | Starts the stream. Calls IMediaControl::Run on the filter graph.
PauseStream | Pauses the stream. Calls IMediaControl::Pause on the filter graph.
StopStream | Stops the stream. Calls IMediaControl::Stop on the filter graph.

See Also

CMSPStream


CMSPStream Public Methods, Called by MSPCall Object

CMSPStream public methods | Description
Init | Called by the MSPCall when the stream is created.
ShutDown | Called by the MSPCall to unselect all terminal objects and release the call object.
GetState | Called by the MSPCall object to get the current status of the stream.
HandleTSPData | Derived call object may call this method to let the stream handle the TSP commands.
ProcessGraphEvent | Called by the MSPCall object to let the stream handle graph events.


CMSPStream::Init

This method is called by the MSPCall when the stream is created. It initializes the members, calls MSPCallAddRef on the call object, and queries for various interfaces on the filter graph.

virtual HRESULT Init(
  HANDLE hAddress,
  CMSPCallBase *pMSPCall,
  IMediaEvent *pGraph,
  DWORD dwMediaType,
  TERMINAL_DIRECTION Direction
);

Parameters

hAddress
Handle for address associated with this call.
pMSPCall
Pointer to MSP basic calling handler class, CMSPCallBase.
pGraph
Pointer to IMediaEvent interface for the stream's filter graph. This DirectShow interface supports event notification to the application from the filter graph and from filters within the filter graph.
dwMediaType
Descriptor of media type for stream.
Direction
Descriptor of terminal direction.

See Also

CMSPStream


CMSPStream::ShutDown

This method is called by the MSPCall object. It unselects all the terminal objects (via UnselectTerminal). It also calls MSPCallRelease on the call object. This is needed to break the circular refcount.

virtual HRESULT ShutDown();

Parameters

This function has no parameters.


CMSPStream::GetState

This method is called by the MSPCall object. It returns the current status of the stream. The default implementation returns E_NOTIMPL.

virtual HRESULT GetState(
  DWORD *pdwStatus
);

Parameters

pdwStatus
Pointer to indication of stream's state. The precise return value is implementation dependent. An example set of types that might be defined for this purpose: STRM_RUNNING, STRM_PAUSED, and STRM_STOPPED.

See Also

CMSPStream


CMSPStream::HandleTSPData

This method may be called by the derived call object to let the stream handle the TSP commands. The default implementation returns S_OK. Override this method to implement the stream-specific portion of your MSP-TSP communication. Note that the base call object classes do not call this method; if you want to use it, you must also override the ReceiveTSPCallData method to dispatch the TSP data to your streams. The stream dispatch information, if any, will be contained in the opaque buffer.

virtual HRESULT HandleTSPData(
  BYTE *pData,
  DWORD dwSize
);

Parameters

pData
Pointer to opaque buffer containing implementation-dependent information.
dwSize
Size in bytes of opaque buffer.

See Also

CMSPStream


CMSPStream::ProcessGraphEvent

This method is called by the MSPCall object to let the stream handle graph events. The default implementation returns S_OK and does nothing. Derived MSPs must override this method if they want to propagate graph events to the application or take some other action in response to graph events.

virtual HRESULT ProcessGraphEvent(
  long lEventCode,
  long lParam1,
  long lParam2
);

Parameters

lEventCode
Implementation-dependent descriptor of the graph event.
lParam1
Implementation-dependent information on the graph event.
lParam2
Implementation-dependent information on the graph event.

See Also

CMSPStream


CMSPStream Overriden CComObject Methods

CMSPStream overriden CComObject methods | Description
FinalRelease | Releases the filter graph pointers.


CMSPStream::FinalRelease

Releases the filter graph pointers.

virtual void FinalRelease();

Parameters

This method has no parameters.


CMSPStream Pure Virtual Methods

These methods must be overridden by derived classes.

CMSPStream pure virtual methods | Description
get_Name | Gets the name of the stream. The derived stream class should provide a name that allows a user to make meaningful distinctions between streams if this is called for in the application's user interface.

See Also

CMSPStream


CBaseTerminal

CBaseTerminal is a terminal base class applicable to both static and dynamic terminals. It is completely generic, so any terminal implementation can derive from this class directly or indirectly.

Defined in Mspterm.h.


CSingleFilterTerminal

CSingleFilterTerminal is an additional terminal base class applicable to both static and dynamic terminals. It is derived from CBaseTerminal and makes the implementation more specific by assuming that the terminal has a single DirectShow filter. When this condition is met, deriving a terminal implementation from CSingleFilterTerminal is much easier than deriving from CBaseTerminal.

Defined in MSPterm.h.


CVideoCaptureTerminal

The CVideoCaptureTerminal terminal is derived from CSingleFilterTerminal and implements a static video capture terminal using a single DirectShow filter. It does not support certain advanced video capture interfaces that are applicable only to WDM video capture. Most MSPs will not need to override the implementation of this terminal.

Defined in MSPtmvc.h.


CAudioCaptureTerminal

The CAudioCaptureTerminal terminal is derived from CSingleFilterTerminal and implements a static audio capture terminal for wave devices using the DirectShow wavein filter. Most MSPs will not need to override the implementation of this terminal.

Defined in MSPtmac.h.

Remarks

The put_Balance and get_Balance methods of CAudioCaptureTerminal are not implemented and will return E_NOTIMPL.


CAudioRenderTerminal

The CAudioRenderTerminal terminal is derived from CSingleFilterTerminal and implements a static audio render terminal for wave devices using the DirectShow waveout filter. Most MSPs will not need to override the implementation of this terminal.

Defined in MSPtrmar.h.

Remarks

The put_Balance and get_Balance methods of CAudioRenderTerminal are not implemented and will return E_NOTIMPL.


CMSPThread

The CMSPThread class implements the MSP's worker thread. The base classes use this worker thread for a number of purposes. A generic and lightweight work item mechanism is provided to allow the derived MSP to use this thread for its own synchronous or asynchronous work items, whatever they may be. The thread also pumps messages and supports handling of APCs (although APCs are not used in the base classes).

When multiple like addresses are present (that is, when the same MSP implementation from the same DLL is instantiated multiple times), the thread class ensures scalability by automatically using a single thread for all the addresses. The interface to the thread class is such that the MSP implementation can think of the thread class as a private thread and need not care about the other addresses that may be sharing it.

Defined in MSPthrd.h.


Open Issues

  • Before the Windows 2000 final release, the call shutdown path may change slightly to make it easier to make shutdown of a call an asynchronous operation (helps to protect against deadlocks for MSPs that support video).
  • Methods and members of worker thread class, terminal base classes, and derived static terminals are documented only by the header files themselves.


TAPI 3.0 Terminal Manager

The TAPI 3.0 Terminal Manager is created by Tapi3.dll at the request of an MSP, and is used by the MSP for tasks such as the creation and deletion of dynamic terminals.

The precise implementation details for an MSP's dynamic terminals are beyond the scope of this documentation. However, many authors may choose to use some of the capabilities of the Media Streaming Terminal (MST). This terminal is based on DirectShow and filters specific to a given protocol may be written and used in conjunction with the MST.


Media Streaming Terminal (MST)

The Media Streaming Terminal (MST) is a dynamic terminal based on use of DirectShow filters. An MSP written using the TAPI 3.0 MSP Base Classes will incorporate an MST, but MSP authors may choose to implement it without using the base classes.

To invoke MST creation, an application makes a call to ITTerminalSupport::CreateTerminal using pTerminalClass set to CLSID_MediaStreamTerminal.

The ITAMMediaFormat and ITAllocatorProperties interfaces are then exposed on the terminal, allowing an application to tune streaming performance. These interfaces are declared in Tapi3.h.

Implementation and use of an MST requires familiarity with DirectShow filters and filter graph management. Please refer to the DirectShow material under the Graphic and Multimedia Services node of the Platform SDK. The Multimedia Streaming Reference will be particularly useful to MSP authors.


TAPI 3.0 Terminal Manager Reference

Terminal Manager interfaces | Description
ITTerminalControl | Provides methods to connect and disconnect a terminal from a filter graph, and run or stop a renderer.
ITTerminalManager | Provides methods to create dynamic terminals.
ITTerminalManager2 | Provides methods to retrieve information about pluggable terminal classes registered in the current system; derives from the ITTerminalManager interface.

See Also

ITTerminal, ITTerminalSupport


ITTerminalControl

The ITTerminalControl interface provides methods to get the MSP handle, connect and disconnect a terminal from a filter graph, and run or stop a renderer.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTerminalControl methods | Description
get_AddressHandle | Gets MSP address handle.
ConnectTerminal | Connects filters and returns a set of pins for connection.
CompleteConnectTerminal | Completes terminal connection.
DisconnectTerminal | Disconnects internal filters and removes them from the filter graph.
RunRenderFilter | Starts the rightmost render filter in the terminal.
StopRenderFilter | Stops the rightmost render filter in the terminal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.


ITTerminalControl::get_AddressHandle

Gets MSP address handle.

HRESULT get_AddressHandle(
  MSP_HANDLE *phtAddress
);

Parameters

phtAddress
[out] Pointer to MSP address handle.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The phtAddress parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalControl


ITTerminalControl::CompleteConnectTerminal

Completes terminal connection.

HRESULT CompleteConnectTerminal();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.

Remarks

This method always returns S_OK. If an MSP cannot connect the terminal, the error return must occur during the call to ITTerminalControl::ConnectTerminal.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalControl


ITTerminalControl::ConnectTerminal

Connects filters and returns a set of pins for connection. Enters each of the internal filters into the filter graph, connects the internal filters together (if applicable) and returns a set of pins for connection.

HRESULT ConnectTerminal(
  IGraphBuilder *pGraph,
  DWORD dwTerminalDirection,
  DWORD *pdwNumPins,
  IPin **ppPins
);

Parameters

pGraph
[in] Pointer to graph builder interface.
dwTerminalDirection
[in] Indicator of terminal direction.
pdwNumPins
[in,out] Pointer to number of pins.
ppPins
[out] Pointer to array of pins to be used for media transport related to the current terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
TAPI_E_NOTENOUGHMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_TERMINALINUSE | The current terminal is already in use.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalControl


ITTerminalControl::DisconnectTerminal

Disconnects internal filters and removes them from the filter graph.

HRESULT DisconnectTerminal(
  IGraphBuilder __RPC_FAR *pGraph,
  DWORD dwReserved
);

Parameters

pGraph
[in] Pointer to the interface for the graph to be disconnected.
dwReserved
[in] Reserved; not currently used.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_UNEXPECTED | An unknown error occurred during the disconnect attempt.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalControl


ITTerminalControl::RunRenderFilter

Starts the rightmost render filter in the terminal. Needed for dynamic filter graphs.

HRESULT RunRenderFilter();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalControl


ITTerminalControl::StopRenderFilter

Stops the rightmost render filter in the terminal. Needed for dynamic filter graphs.

HRESULT StopRenderFilter();

Parameters

This method has no parameters.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_NOTIMPL | Method not implemented.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalControl


ITTerminalManager

The ITTerminalManager interface is used by the MSP to create dynamic terminals.

The ITTerminalManager2 interface exposes methods that retrieve information about pluggable terminal classes registered in the current system. ITTerminalManager2 is derived from the ITTerminalManager interface.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTerminalManager methods | Description
GetDynamicTerminalClasses | Gets list of terminal classes.
CreateDynamicTerminal | Create a dynamic terminal of a specified terminal class, media type, and direction.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalManager2


ITTerminalManager::CreateDynamicTerminal

Create a dynamic terminal of a specified terminal class, media type, and direction.

HRESULT CreateDynamicTerminal(
  IUnknown *pOuterUnknown,
  IID iidTerminalClass,
  DWORD dwMediaType,
  TERMINAL_DIRECTION Direction,
  MSP_HANDLE htAddress,
  ITTerminal **ppTerminal
);

Parameters

pOuterUnknown
[in] If MSP will aggregate the terminal object, set to IUnknown interface pointer for MSP object. Usually this is set to NULL.
iidTerminalClass
[in] GUID identifying class of terminal to be created.
dwMediaType
[in] Descriptor of media type for stream.
Direction
[in] TERMINAL_DIRECTION descriptor of the media stream direction for terminal.
htAddress
[in] MSP handle.
ppTerminal
[out] Pointer to ITTerminal interface for new terminal.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The fMessageWaiting parameter is not valid.
E_POINTER | The ppAddress parameter is not a valid pointer.

Remarks

When choosing a value for pTerminalClass, the only terminal class GUIDs that can be used are those that correspond to terminals that are "dynamically" created. For example, from all terminal classes currently defined by TAPI3, only the following can be used with CreateTerminal: CLSID_MediaStreamTerminal and CLSID_VideoWindowTerm.

In addition, only those dynamic terminal classes that are supported on this address can be used. The application can discover these values by using ITTerminalSupport::EnumerateDynamicTerminalClasses or ITTerminalSupport::get_DynamicTerminalClasses.

The application must obtain the pTerminalClass BSTR in two steps: call StringFromIID to convert the GUID to an LPOLESTR, then call SysAllocString to convert the LPOLESTR to a BSTR.

The application must use SysFreeString to free the memory allocated for the pTerminalClass parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalManager, media type, TERMINAL_DIRECTION


ITTerminalManager::GetDynamicTerminalClasses

Gets list of terminal classes for a set of media types.

HRESULT GetDynamicTerminalClasses(
  DWORD dwMediaTypes,
  DWORD *pdwNumClasses,
  IID *pTerminalClasses
);

Parameters

dwMediaTypes
[in] Pointer to media types.
pdwNumClasses
[in,out] Number of terminal classes returned.
pTerminalClasses
[out] Pointer to list of terminal classes.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_POINTER | The pdwNumClasses or the pTerminalClasses parameter is not a valid pointer.
TAPI_E_NOTENOUGHMEMORY | Insufficient memory exists to perform the operation.
TAPI_E_NOTSUPPORTED | Dynamic terminals not supported on this address.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Version: Requires TAPI 3.0 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalManager


ITTerminalManager2

[This is preliminary documentation and subject to change.]

The ITTerminalManager2 interface exposes methods that retrieve information about pluggable terminal classes registered in the current system. ITTerminalManager2 is derived from the ITTerminalManager interface.

Methods in Vtable Order

IUnknown Methods

IDispatch Methods

ITTerminalManager2 methods | Description
GetPluggableSuperclasses | Gets the public CLSIDs for all pluggable terminal superclasses in the registry.
GetPluggableTerminalClasses | Gets the terminal classes for all pluggable terminals registered under a terminal superclass.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalManager


ITTerminalManager2::GetPluggableSuperclasses

[This is preliminary documentation and subject to change.]

The GetPluggableSuperclasses method gets the public CLSIDs for all pluggable terminal superclasses in the registry.

HRESULT GetPluggableSuperclasses(
  DWORD * pdwNumSuperclasses,
  IID * pSuperclasses
);

Parameters

pdwNumSuperclasses
[in,out] The number of superclasses retrieved. If pSuperclasses is NULL, this argument is used to get the total number of pluggable terminal superclasses registered in the registry. If pSuperclasses is not NULL, this argument is used to pass the size, in IIDs, of the pSupperclasses buffer, and the method returns the number of IIDs copied into buffer memory.
pSuperclasses
[out] Pointer to an IID buffer allocated by the user.

If the buffer is NULL, the method returns the count of superclasses in the buffer. Otherwise, the method returns the IIDs of the pluggable terminal superclasses registered on the system.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_FAIL | Method failed.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalManager2


ITTerminalManager2::GetPluggableTerminalClasses

[This is preliminary documentation and subject to change.]

The GetPluggableTerminalClasses method lists the terminal classes for all pluggable terminals registered under a terminal superclass.

HRESULT GetPluggableTerminalClasses(
  IID iidSuperclass,
  DWORD dwMediaTypes,
  DWORD * pdwNumClasses,
  IID * pTerminalClasses
);

Parameters

iidSuperclass
[in] A BSTR that represents the CLSID for the parent superclass.
dwMediaTypes
[in] Bitwise ORed list of media types. The method returns only terminals that support these media types.
pdwNumClasses
[in,out] If the pTerminalClasses parameter is NULL, this parameter returns the total number of terminals registered under the terminal superclass specified by the iidSuperclass parameter.

If pTerminalClasses is not NULL, and the method completes successfully, this parameter returns a count of the number of terminal IIDs returned in the pTerminalClasses buffer.

pTerminalClasses
[out] Pointer to the buffer to receive the terminals IIDs. This parameter can also be NULL. For more information, see the description of the pdwNumClasses parameter.

Return Values

Value | Meaning
S_OK | Method succeeded.
E_INVALIDARG | The pTerminalClasses parameter doesn't represent an IID or list of IIDs.
E_FAIL | The method failed.
E_POINTER | The pTerminalClasses parameter is not a valid pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Version: Requires TAPI 3.1 or later.
Header: Declared in Termmgr.h.
Library: Use Uuid.lib.

See Also

ITTerminalManager2


Writing a Pluggable Terminal

Normally, a media service provider (MSP) implements terminal creation. Starting with Windows 2000 SP1, TAPI 3 includes pluggable terminals to allow an application to implement terminal creation. Please see the overview on implementing pluggable terminals for additional information on using these terminals.

You should not use pluggable terminals routinely because the full capabilities of a terminal will only be available when an MSP is fully aware of it. Further, you should not attempt to implement pluggable terminals unless you are already familiar with writing media service providers. The techniques and potential problems involved are quite similar.

Provision for a special case of pluggable terminal currently exists for the situation of a conferencing server that needs to add non-Windows 2000 SP1 or nonmulticast H.323 clients to TAPI 3.0 multiparty SDP/IP multicast conferences. Please see the guidelines on using the H323-SDP bridge terminal for additional information.


Implementing Pluggable Terminals

The general requirements for pluggable terminal implementation are:

  • A pluggable terminal's underlying streaming code should match the capabilities of the desired MSPs.
  • The terminal must use DirectShow® filters to work with most MSPs (this is assumed from here on).
  • Audio terminals must support 8 kHz 16-bit mono linear PCM for most MSPs.
  • The terminal should enable free threaded marshalling by implementing IMarshal. The terminal can do this by calling the COM API CoCreateFreeThreadedMarshaler and aggregating IMarshal to the returned pointer. The terminal object's destructor should call IMarshal->Release.
  • The terminal should implement or aggregate any additional terminal-specific interfaces that are appropriate.
  • The terminal implementation must be thread-safe.
  • The terminal implementation must #include Termmgr.h for the definition of ITTerminalControl. This is in addition to the usual includes and libs that are needed for TAPI 3.0 or TAPI 3.0 applications under Windows 2000 SP1.

Interface and method implementation notes:

The terminal must implement ITTerminal (dual interface–vtable + IDispatch).

ITTerminal::get_TerminalClass

The terminal must return a BSTR representation of a GUID you've picked that identifies your type of terminal. Allocate the BSTR via SysAllocString. To convert from GUID to BSTR, call StringFromCLSID, SysAllocString, and CoTaskMemFree.

ITTerminal::get_TerminalType

The terminal should generally return TT_DYNAMIC if an application implements the terminal. Returning TT_STATIC will also work, and returning this value may be appropriate if the terminal corresponds to a hardware device; however, doing this may be confusing to users because a static terminal will not be present in the MSP's static terminal enumeration.

ITTerminal::get_State

If the terminal implementation does not arbitrarily limit the number of streams that the terminal can be concurrently connected to, then the terminal should always return TS_NOTINUSE.

Otherwise, the terminal implementation arbitrarily limits the number of streams that the terminal can be connected to at a time. In this case, the terminal should keep a count of how many streams it is connected to. The terminal should increment this internal count on a successful ITTerminalControl::ConnectTerminal call and decrement it on a successful ITTerminalControl::DisconnectTerminal call. In ITTerminal::get_State, it should return TS_INUSE if this count is equal to the maximum number of streams that the terminal can be selected on at a time; otherwise, it should return TS_NOTINUSE. Note that if the limit is one, the count can simply be a Boolean or a TERMINAL_STATE value.

ITTerminal::get_Name

The terminal should return a BSTR name of its choice, allocated via SysAllocString. This name should be meaningful to the user and should be localized.

ITTerminal::get_MediaType

The terminal should return its media type, either TAPIMEDIATYPE_AUDIO or TAPIMEDIATYPE_VIDEO.

ITTerminal::get_Direction

The terminal returns the TERMINAL_DIRECTION enum value indicating the direction of the terminal. If the terminal is bidirectional (for example, a bridge), then it must return TD_BIDIRECTIONAL.

The terminal must implement ITTerminalControl (vtable only).

ITTerminalControl::get_AddressHandle

An application-provided terminal should always return NULL as the address handle. This indicates to the MSP that this terminal was not created on a specific MSP address object.

ITTerminalControl::ConnectTerminal

On this call, the terminal will add its filter(s) to the given graph and connect them to each other, if applicable. Then the terminal should return the pin(s) exposed by the terminal for the stream direction specified.

A terminal that does not support concurrent connection to multiple streams would set an internal variable to TS_INUSE on successful completion of this method.

The terminal can use the dwTerminalDirection parameter from this call to determine the direction of the stream that it is being connected to. This is required for bidirectional terminals.

Note Typically (in the MSP base classes and in all known MSPs), the MSP stream code will fail the connection if the terminal returns more than one pin from a single ConnectTerminal call. This is fine, because a terminal that returns more than one pin during connection requires the MSP to have special knowledge of the terminal to make use of the extra pins effectively.

ITTerminalControl::CompleteConnectTerminal

The terminal should just return S_OK. The terminal may also do post-connection initialization if it needs to.

ITTerminalControl::DisconnectTerminal

The terminal should do whatever is needed to disconnect the terminal from the rest of the graph. Typically this involves removing all the terminals' filters from the graph and setting the terminal state to TS_NOTINUSE.

ITTerminalControl::RunRenderFilter

The terminal should just return E_NOTIMPL.

ITTerminalControl::StopRenderFilter

The terminal should just return E_NOTIMPL.


H323-SDP Bridge Terminal

The H323-SDP bridge is based on the TAPI 3.0 H323 service providers (H323 MSP and H323 TSP) plus the IP conferencing service providers (IPConf MSP and IPConf TSP). Starting with Windows 2000 SP1, these service providers expose new interfaces that can be used by a conferencing server to bridge an H.323 client call and cause it to appear to the conference as an SDP multicast call.

Audio streaming for both G.711 and G.723 protocols is supported on the H323 side of the bridge and both G.711 and GSM6.10 on the SDP side. G.711 is the preferred format. The H323 side of the bridge will negotiate G.711 whenever possible. Audio streams from the SDP side are mixed and then sent to the H.323 client. H.323 clients receive the same audio experience as the SDP/IP Multicast participants. The negotiated audio stream from an H.323 client needs to be forwarded and transcoded to the multicast address. The bridge terminal handles audio frames of different sizes.

For video streaming, only the H.263 protocol is supported on H.323 calls that require SDP bridging. The H.323 client can receive only one video window at a time. The conferencing server needs to make video switching decisions based on currently active speaker. The video stream sent to the H.323 client takes a lower priority than the audio stream by limiting the video frame rate.

See the IH323LineEx, IKeyFrameControl, and IMulticastControl interfaces for details on the manipulation of the bridge.


A

Analog Display Services Interface (ADSI)
A Bellcore standard defining a protocol on the flow of information between a switch, a server, a voice mail system, or service bureau, for example, and a subscriber's telephone, PC, data terminal, or other communicating device with a screen. ADSI enables a text version of the conversation to be displayed on the screen during the telephone connection. As an example, the user dials into a voice mail account and receives an audio menu for the voice mail functions while the screen displays the menu in text form.
Assisted Telephony
The set of functions that are not just dedicated to telephonic functionality, but are designed to make the establishment of voice calls and media calls available to any Win32-based application. For additional information, see Assisted Telephony in the telephony overview. See also Basic Telephony, Extended Telephony, Supplementary Telephony.
asynchronous
Data transmission method that allows characters to be sent at irregular intervals over a line by preceding each character with a start bit and following it with a stop bit. See also synchronous.


B

B channel
A bearer channel that is a fundamental component of ISDN interfaces. It carries 64,000 bits per second (bps) in both directions, is circuit-switched, and is able to carry either voice or data. For additional information, see Bearer Mode. See also D channel, Integrated Services Digital Network (ISDN).
band
The range of frequencies between two defined points.
bandwidth
In communications, the difference between the highest and lowest frequencies in a given range. For example, a telephone accommodates a bandwidth of 3000 Hz, the difference between the lowest (300 Hz) and highest (3300 Hz) frequencies it can carry.
Bandwidth Allocation Control Protocol (BACP)
The set of rules that manages bandwidth over dynamic multi-link PPP connections. See also multi-link PPP, point-to-point protocol (PPP).
Basic Rate Interface (BRI-ISDN)
The standard ISDN line, consisting of two B channels and one D channel. See also Integrated Services Digital Network (ISDN), Primary Rate Interface (PRI-ISDN).
Basic Telephony
An elementary level of telephony service, with a minimal subset of features, that provides a minimum set of functions that corresponds to Plain Old Telephone Service (POTS). TAPI service providers are required to support all Basic Telephony functions. See also Assisted Telephony, Extended Telephony, Supplementary Telephony.
BRI-ISDN
See Basic Rate Interface (BRI-ISDN).
bps
See bits per second (bps).
bits per second (bps)
Transfer-rate measurement indicating how many bits of computer data are sent in a one-second period through a modem over a telephone line.


C

call classification
TAPI process that reports changes in the type of media stream (voice, fax, data modem, and so on) to participating applications.
call progress monitoring
The process of listening for audible tones such as a dial tone, special information tones, busy signals, and ringback tones to determine the state of a call (its progress through the network).
call redirection
A function that allows an application to deflect an offering call to another address without first answering the call. Call redirection differs from call forwarding in that call forwarding is performed by the switch without the involvement of the application; redirection can be done on a call-by-call basis by the application, for example, driven by caller ID information. It differs from call transfer in that transferring a call requires that the call first be answered. See also called-ID, caller-ID, redirecting ID, redirection ID.
called-ID
Identifies the original destination address of a call. See also call redirection.
caller-ID
Identifies the originating address of a call. See also call redirection.
central office
Telephone company's local facility that provides telephone service in a specific area. Typically, subscribers' lines are joined to switching equipment that connects other subscribers to each other, locally and over long distance. Also called CO.
Centrex
A business telephone service offered by a local telephone company from a local, central office.
computer-centric connection
A connection that uses a computer add-in card or external box that is connected to both the telephone network and the phone set. Compare phone-centric connection.
connected-ID
Identifier for the party to which the call was actually connected. This may be different from the called party if the call was diverted.


D

D channel
A data channel of the ISDN interface. It is one of the three standard channels on a Basic Rate ISDN line. On a BRI-ISDN line, a D channel can carry signaling information and low-speed packet data at a rate of 16,000 bps. On a PRI-ISDN line, the D channel runs at 64,000 bps. See also Basic Rate Interface (BRI-ISDN), B channel, Primary Rate Interface (PRI-ISDN).
device class
A group of related physical devices or device drivers through which applications send and receive the information or data that makes up a call. For a list, see TAPI Device classes.
DID
See direct inward dialing (DID).
direct inward dialing (DID)
An ability provided by virtually all modern PBXs that allows an external caller to reach an internal extension by dialing a standard seven-digit telephone number without having to pass through an operator or attendant. See also private branch exchange (PBX).
DLL
See dynamic-link library (DLL).
dynamic-link library (DLL)
A feature that allows executable code modules to be loaded on demand and linked at run time. This enables the library-code fields to be updated automatically, transparent to applications, and then unloaded when they are no longer needed.


E

Extended Telephony
Level of telephony service in which the API provides well-defined API extension mechanisms that enable application developers to access service provider-specific functions not directly defined by the Telephony API. See also Assisted Telephony, Basic Telephony, Supplementary Telephony.


H

H.323
The H.323 protocol is the International Telecommunications Union - Telecommunications (ITU-T) standard for real-time multimedia communications and conferencing over packet-based networks.


I

Integrated Services Digital Network (ISDN)
A completely digital telephone/telecommunications network for carrying voice, data, images, and video at high speed by sending digitally encoded signals at speeds of up to 144,000 bps on Basic Rate Interface (BRI-ISDN) lines and much higher on Primary Rate Interface (PRI-ISDN) lines. ISDN is composed of at least three channels and as many as 32 channels, for simultaneous, independently operated transmission of voice and data. See also Basic Rate Interface (BRI-ISDN), Primary Rate Interface (PRI-ISDN).
Interactive Voice Response (IVR) Application
A telephony application that leads a telephone caller through a hierarchy of menus, delivers voice responses, collects voice and data inputs, and performs other operations on behalf of the caller or the program sponsor. See also Web Telephony.
inverse multiplexing
The process whereby bandwidth enables a call to transmit more information at the same time in the same timeframe than information from a single signal transmitted over a single channel. This is accomplished by splitting a single high-speed channel into multiple signals, transmitting the multiple signals over multiple facilities operating at a lower rate than the original signal, and then recombining the separately transmitted portions into the original signal at the original rate. See also bandwidth.
IP Multicast
IP multicast is a scheme for sending the same data to several machines simultaneously. A network with multicast-aware routers enabled will be able to convey such information much more rapidly by sending packets just once between routers. For additional information, see About Rendezvous IP Telephony Conferencing.
ISDN
See Integrated Services Digital Network (ISDN).


K

Kbps
See kilobits per second (Kbps).
kHz
See kilohertz (kHz).
kilobits per second (Kbps)
One thousand bits per second. Standard measure of data rate and transmission capacity.
kilohertz (kHz)
In data communications, kHz means a thousand bits per second. In computer memory terms, kHz means 1,024, which is the figure for two raised to the 10th power.


L

line device
A physical channel composed of a telephone line and the hardware to control it such as a fax board, a modem, or an ISDN card. The simplest kind of line device corresponds to exactly one telephone line.
line device class
A device-independent representation of a physical line device, such as a modem.
local loop
The part of the telephone network between the telephone and the telephone company's central switching office. Within this loop, human speech from a household telephone is usually transmitted in analog format, and the digital data from a computer must first be converted to analog by a modem. Digital networks are gradually replacing analog in the local loop.


M

MAPI
See Microsoft Messaging API (MAPI).
Mbps
See megabits per second (Mbps).
media stream
The type of information exchanged over a call.
media type
The form in which data is transmitted on a line.
megabits per second (Mbps)
1,544,000 bits per second (bps). See also bits per second (bps).
megahertz (MHz)
One million cycles per second; a unit of frequency used to measure band and bandwidth. See also band, bandwidth.
MHz
See megahertz (MHz).
Microsoft Messaging API (MAPI)
Set of API functions and an OLE interface that lets messaging clients, such as Microsoft Exchange, interact with various message service providers and various computer telephony servers running Windows NT Server/Windows 2000 Server.
Multicast
See IP Multicast.
multi-link PPP
A communications protocol that allows the combination of two or more B channels into a single, faster PPP connection. With multi-link PPP, you can have a 128-Kbps PPP connection over a Basic Rate ISDN line. See also Basic Rate Interface (BRI-ISDN), point-to-point protocol (PPP).


P

phone-centric connection
A connection that consists of a single POTS line in which the computer is connected to the switch through the desktop phone set. Compare computer-centric connection.
Plain Old Telephone Service (POTS)
Basic telephony service supplying standard single-line telephones, telephone lines, and access to the public switched network.
point-to-point protocol (PPP)
A communications protocol that allows a computer to connect to other computers over a standard dial-up telephone line using a high-speed modem.
POTS
See Plain Old Telephone Service (POTS).
PRI-ISDN
See Primary Rate Interface (PRI-ISDN).
Primary Rate Interface (PRI-ISDN)
A type of ISDN service that offers 23 B channels at 64 Kbps and one D channel at 64 Kbps (23B+D). In Europe, PRI provides for 30 B channels and two D channels (30B+2D). See also Basic Rate Interface (BRI-ISDN).
private branch exchange (PBX)
A private telephone switching system, usually located on a customer's premises with an attendant console. The PBX is connected to a common group of lines from one or more central offices to provide service to a number of individual phones, such as in a hotel, business, or government office. PBXs often use proprietary digital-line protocols, although some are analog based.
provisioning
The combination of device and service options that make up an ISDN line. When you order your ISDN line, the telephone company provisions the line, that is, it configures your ISDN service according to the physical capabilities of the switch, as well as the options you choose.
public switched telephone network (PSTN)
The local analog telephone network, which provides 3.1 kHz voice-grade quality of service (its bearer mode).


R

redirecting-ID
Identifies the address that redirected the call. See also call redirection.
redirection-ID
Identifies the address to which the call was redirected. See also call redirection.


S

service provider
A dynamic-link library that supports communications over a telephone network through a set of exported service functions. The service provider responds to telephony requests, sent to it by the TAPI dynamic-link library, by carrying out the low-level tasks necessary to communicate over the telephone network. In this way, the service provider, in conjunction with TAPI, shields applications from the service- and technology-dependent details of the telephone network communication.
subaddressing
A capability provided on ISDN lines that allows more information than just a single telephone number to be used when dialing.
Supplementary Telephony
Level of service that provides advanced switch features such as hold, transfer, and so on. All supplementary services are optional; that is, the service provider is not required to support them. See also Assisted Telephony, Basic Telephony, Extended Telephony.
Switched 56
A switched data service that lets the user dial someone else and transmit at full duplex, digital synchronous 56 Kbps for the price of a phone call.
synchronous
Data transmission method in which there is constant time between successive bits, characters, or events. The timing is achieved by the sharing of a single clock. Each end of the transmission synchronizes itself with the use of clocks and information sent along with the transmitted data. Characters are spaced by time, not by start and stop bits. See also asynchronous.


T

T1/E1
A digital transmission link with a capacity of 1,544 Mbps. In the US, this link is called T1. In Europe, it is called E1. See also megabits per second (Mbps).
TAPI
See Telephony Application Programming Interface (TAPI).
tapisrv.exe
A support-service application that provides an execution context for the TAPI dynamic-link library to carry out duties such as allocating memory or accessing data structures that have been swapped out to disk.
TDD
See Telecommunications Devices for the Deaf (TDD).
Telecommucations Devices for the Deaf (TDD)
A data device for the transmission of coded signals. Typically, the device is a simple computer terminal consisting of a keyboard, acoustic coupler, and display, and runs at 300 baud.
telephony
The science of transmitting voice, data, video, or image signals over a distance using technology that integrates computers with the telephone network.
Telephony Application Programming Interface (TAPI)
Set of functions that allows programming of telephone line-based devices in a device-independent manner, giving personal telephony to users. TAPI supports both speech and data transmission, allows for a variety of terminal devices, and supports complex connection types and call-management techniques such as conference calls, call waiting, and voice mail. TAPI allows all elements of telephone usage—from the simple dial-and-speak call to international e-mail—to be controlled within applications developed for the Microsoft® Win32® application programming interface (API). See the Microsoft Telephony Overview.
Telephony Service Provider Interface (TSPI)
Tool for creating service providers for the Microsoft Windows family of operating systems that support the Microsoft Win32 application programming interface (API). Win32 TSPI defines how the network shares information with Windows Telephony, which in turn talks to the API, which talks to the Windows Telephony applications. For additional information, see Telephony Service Provider Interface (TSPI).
third-party call control
A party call-control model that allows an application to establish or answer a call between any two parties.
threads
Individual processes within a single application.
tick count
The number of milliseconds since Windows started.
time to live (TTL)
A value in the range 0 through 255 that defines the scope within which multicast packets should be sent over a network using Internet Protocol (IP). The scope is defined in terms of how local or remote a packet's destination is. Each router decrements the TTL by one. When the value reaches a predefined lower limit, the router throws the packet away. Current multicast backbone (MBONE) requirements, available at the ftp://ftp.isi.edu/mbone/faq.txt site, define the following standard scopes: local network, 1; local site, 15; region, 63; world, 127. Other settings may have local meaning; for example, 31 might indicate all sites within a particular organization.
timestamp
An imprint of time/date created when a specific event or process takes place.
TSPI
See Telephony Service Provider Interface (TSPI).
TTL
See time to live (TTL).
twisted pair
Regular telephone wiring. Each telephone wire is actually a pair of wires.


U

UniModem
The universal modem driver in TAPI. UniModem is a driver-level component that uses modem description files to control its interaction with the communications driver, VCOMM. See also VCOMM.
user-user information
Information that is sent from one user to another by the remote station (ISDN). For additional information:

TAPI 2: lineReleaseUserUserInfo, lineSendUserUserInfo.

TSPI: TSPI_lineReleaseUserUserInfo, TSPI_lineSendUserUserInfo.

TAPI 3: ITCallInfo::get_CallInfoBuffer, ITCallInfo::put_CallInfoBuffer, ITCallInfo::ReleaseUserUserInfo.


V

VCOMM
A communications device driver within TAPI. VCOMM can assign protected mode to TAPI services and allows Windows applications and drivers to use ports and modems. See also UniModem.
voice signal
Considered to be any signal that can travel over a 3.1 kHz-bandwidth channel.


W

Web Telephony
An application platform that supports dual-access Web sites (accessible by telephone or Internet browser) and HTML-based IVR applications. The platform includes a run-time engine integrated into the Windows 2000 server, a COM-based administration interface for installing and configuring Web Telephony applications, and access to the TAPI 3.0 call object and scripting API, for implementing telephony operations.
Web Telephony Engine (WTE)
A run-time component of the Windows 2000 Server that provides support for HTML-based IVR applications, and dual-access Web sites (a Web site that is accessible by telephone as well as through a graphical browser). See also Web Telephony.
Windows Open Services Architecture (WOSA)
Software architecture that provides a single system-level interface for connecting front-end applications with back-end services. Windows Telephony is part of WOSA.


Symbols

2B+D
Designation for the way a Basic Rate ISDN line is configured, using two B channels and one D channel. See also B channel, Basic Rate Interface (BRI-ISDN), D channel.


TAPI 2 to TAPI 3 Cross-Reference

The following material provides some assistance to programmers familiar with the TAPI 2 C API in locating appropriate methods in the TAPI 3 COM API. This section is not intended to be exhaustive, and provides cross-referencing only in selected areas.


ITCallInfo TAPI 2 to TAPI 3 Cross-Reference

Information | TAPI 2 | TAPI 3, RC 1
Address types | lineGetCallInfo, dwAddressType member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_CALLERIDADDRESSTYPE, CIL_CALLEDIDADDRESSTYPE, or CIL_CONNECTEDIDADDRESSTYPE member of CALLINFO_LONG.
Address interface pointer | NA | ITCallInfo::get_Address
Application-specific information | lineGetCallInfo, dwAppSpecific member of LINECALLINFO lineSetAppSpecific | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_APPSPECIFIC member of CALLINFO_LONG.
Bearer mode | lineGetCallInfo, dwBearerMode member of LINECALLINFO lineSetCallParams | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_BEARERMODE member of CALLINFO_LONG.
Call data buffer | lineGetCallInfo, dwCallDataSize and dwCallDataOffset members of LINECALLINFO lineSetCallData | ITCallInfo::GetCallInfoBuffer, called with the CIB_CALLDATABUFFER member of CALLINFO_BUFFER
CallHub interface pointer | NA | ITCallInfo::get_CallHub
Call ID | lineGetCallInfo, dwCallID member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_CALLID member of CALLINFO_LONG.
Call origin | lineGetCallInfo, dwOrigin member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_ORIGIN member of CALLINFO_LONG.
Call parameter flags | lineGetCallInfo, dwCallParamFlags member of LINECALLINFO lineSetCallParams | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_CALLPARAMSFLAGS member of CALLINFO_LONG.
Call privilege | lineGetCallStatus,dwCallPrivilege member of LINECALLSTATUS lineSetCallPrivilege | ITCallInfo::get_Privilege or ITCallInfo::get_CallInfoLong, called with the CIL_NUMBEROFOWNERS or CIL_NUMBEROFMONITORS member of CALLINFO_LONG.
Call Reason | lineGetCallInfo, dwReason member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_REASON member of CALLINFO_LONG.
Call state | lineGetCallStatus,dwCallState member of LINECALLSTATUS. | ITCallInfo::get_CallState
Call treatment | lineGetCallInfo, dwCallTreatment member of LINECALLINFO lineSetCallTreatment | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_CALLTREATMENT member of CALLINFO_LONG.
Called party friendly name | NA | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_CALLEDPARTYFRIENDLYNAME member of CALLINFO_STRING.
Caller ID | lineGetCallInfo with dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, dwCallerIDNameOffset, dwCalledIDSize, dwCalledIDOffset, dwCalledIDNameSize, dwCalledIDNameOffset, or dwCallDataOffset members of LINECALLINFO | ITCallInfo::get_CallInfoString, called with the CIS_CALLERIDNAME, CIS_CALLERIDNUMBER, CIS_CALLEDIDNAME, or CIS_CALLEDIDNUMBER member of CALLINFO_STRING.
Calling party ID | dwCallingPartyIDSize and dwCallingPartyIDOffset members of LINECALLPARAMS | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_CALLINGPARTYID member of CALLINFO_STRING.
Charging information | lineGetCallInfo, dwChargingInfoSize and dwChargingInfoOffset members of LINECALLINFO | ITCallInfo::GetCallInfoBuffer, called with the CIB_CHARGINGINFOBUFFER member of CALLINFO_BUFFER
Comment | lineGetCallInfo, dwCommentSize and dwCommentOffset members of LINECALLINFO | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_COMMENT member of CALLINFO_STRING.
Compatibility buffer (ISDN Q.931) | lineGetCallInfo, dwHighLevelCompSize, dwHighLevelCompOffset, dwLowLevelCompSize, or dwLowLevelCompOffset members of LINECALLINFO. | ITCallInfo::GetCallInfoBuffer, called with the CIB_HIGHLEVELCOMPATIBILITYBUFFER or CIB_LOWLEVELCOMPATIBILITYBUFFER member of CALLINFO_BUFFER
Completion ID | lineGetCallInfo, dwCompletionID member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_COMPLETIONID member of CALLINFO_LONG.
Connected ID name | lineGetCallInfo, dwConnectedIDSize, dwConnectedIDOffset, dwConnectedIDNameSize, or dwConnectedIDNameOffset member of LINECALLINFO | ITCallInfo::get_CallInfoString, called with the CIS_CONNECTEDIDNAME or CIS_CONNECTEDIDNUMBER member of CALLINFO_STRING.
Country code | lineGetCallInfo,dwCountryCode of LINECALLINFO | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_COUNTRYCODE member of CALLINFO_LONG.
Device-specific buffer | lineGetCallInfo, dwDevSpecificSize and dwDevSpecificOffset members of LINECALLINFO | ITCallInfo::GetCallInfoBuffer, called with CIB_DEVSPECIFICBUFFER member of CALLINFO_BUFFER
Displayable address | lineGetCallInfo, dwDisplayableAddressSize and dwDisplayableAddressOffset members of LINECALLINFO | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_DISPLAYABLEADDRESS member of CALLINFO_STRING.
Media types | lineGetCallInfo, dwMediaMode members of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with the CIL_MEDIATYPESAVAILABLE member of CALLINFO_LONG.
Rate | lineGetCallInfo, dwRate member of LINECALLINFO lineSetCallParams | ITCallInfo::get_CallInfoLong or ITCallInfo::put_CallInfoLong, called with the CIL_MAXRATE, CIL_MINRATE, or CIL_RATE member of CALLINFO_LONG.
Redirection | lineGetCallInfo, dwRedirectionIDSize, dwRedirectionIDOffset, dwRedirectionIDNameSize, dwRedirectionIDNameOffset, dwRedirectingIDSize, dwRedirectingIDOffset, dwRedirectingIDNameSize, or dwRedirectingIDNameOffset members of LINECALLINFO | ITCallInfo::get_CallInfoString or ITCallInfo::put_CallInfoString, called with the CIS_REDIRECTIONIDNAME, CIS_REDIRECTIONIDNUMBER, CIS_REDIRECTINGIDNAME, or CIS_REDIRECTINGIDNUMBER member of CALLINFO_STRING.
Trunk | lineGetCallInfo, dwTrunk member of LINECALLINFO | ITCallInfo::get_CallInfoLong, called with CIL_TRUNK member of CALLINFO_LONG.
User/user information | lineGetCallInfo, dwCallDataSize and dwCallDataOffset members of LINECALLINFO lineSendUserUserInfo | ITCallInfo::GetCallInfoBuffer, called with the CIB_USERUSERINFO member of CALLINFO_BUFFER and ITCallInfo::ReleaseUserUserInfo.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.